Town association methods

​

Overview

Town association methods help you accurately connect news articles with specific locations in your searches. These methods use different matching strategies to identify location references in articles, from analyzing news sources to processing natural language patterns.

​

Understanding town association

News articles can mention locations in several ways:

• City names (“San Francisco”)
• Regional terms (“Bay Area”)
• Local landmarks (“Golden Gate Bridge”)
• Contextual references (“the city”)

The Local News API uses five association methods to capture these different reference patterns.

​

Available methods

​

HYPERLOCAL_SOURCES_EXCLUDE_QUERY

Identifies articles from dedicated local news sources that don’t mention other locations.

Query pattern:

NOT ((Alabama OR Alaska OR Texas...) AND (", AL" OR ", TX"))

Use this method when working with:

• City-specific newspapers
• University news portals
• Local government sites
• Regional sections of larger publications

For example:

{
  "name": "San Francisco, California",
  "description": ["HYPERLOCAL_SOURCES_EXCLUDE_QUERY"]
}

​

HYPERLOCAL_SOURCES_INCLUDE_QUERY

Finds exact matches of city names in article titles or content.

Query pattern:

"San Francisco"

Use this method for:

• Finding explicit city mentions
• Analyzing headlines
• Matching specific location names

​

LOCAL_SOURCES_EXCLUDE_QUERY

Searches state-level sources while excluding mentions of other states.

Query pattern:

city_name NOT (Alabama OR Alaska OR Texas...) AND (",AL" OR ",TX"))

Use this method with:

• Regional news outlets
• State-wide publications
• Multi-city coverage sources

​

CITY_STATE_COUNTY_QUERY

Searches for standard location format patterns used in journalism.

Query pattern:

"city, state_code" OR "city, state" OR "city, county"

This method matches formats like:

• “San Francisco, CA"
• "San Francisco, California"
• "San Francisco, San Francisco County”

​

NEAR_CITY_STATE_QUERY

Finds articles where city and state names appear close to each other.

Query pattern:

NEAR("San Francisco", "California", 15)

This method matches phrases like:

• “New development in San Francisco draws attention across California"
• "California’s tech hub San Francisco sees startup growth”

​

Implementation guide

PAYLOAD = {
    "associated_towns": [
        {
            "name": "San Francisco, California",
            "description": ["HYPERLOCAL_SOURCES_INCLUDE_QUERY"],
        }
    ]
}

PAYLOAD = {
    "associated_towns": [
        {
            "name": "San Francisco, California",
            "description": [
                "HYPERLOCAL_SOURCES_EXCLUDE_QUERY",
                "CITY_STATE_COUNTY_QUERY",
            ],
        }
    ]
}

PAYLOAD = {
    "associated_towns": [
        {
            "name": "San Francisco, California",
            "description": ["HYPERLOCAL_SOURCES_EXCLUDE_QUERY"],
        }
    ],
    "search_in_ai_associated_town": True,
}

​

Best practices

​

See also

• Quickstart guide
• Subscription plans
• Endpoints