Find Locations by Name

Our Locations Query Resource allows you to request locations by name, including: 

• states 
• cities
• ZIP codes
• neighborhoods
• places (such as businesses, landmarks, and parks)
• localities (better known as NYC boroughs)
• metro areas
• sub-metro areas
• districts (also known as counties)

Requests

To retrieve locations, send a GET request to our Locations Query Resource formated as follows:

http://news-api.patch.com/v1.1/locations/named/{string}?dev_key={key}&sig={signature}

For example, this query will return up to 10 locations called "Brooklyn":

http://news-api.patch.com/v1.1/locations/named/brooklyn?dev_key={key}&sig={signature}

Note that matching on the text provided is case-insensitive.

To find locations that are ambiguous unless qualified by containing cities and states, separate each region with a URL-encoded comma. For example, this query will return up to 10 locations called "Downtown" within the city of Los Angeles (luckily there's only one!):

http://news-api.patch.com/v1.1/locations/named/downtown%2Clos%20angeles?dev_key={key}&sig={signature}

And this query will return up to 10 locations called "Springfield" within the state of Missouri (only one here too):

http://news-api.patch.com/v1.1/locations/named/springfield%2Cmo?dev_key={key}&sig={signature}

Results

The results for requests for locations matching any string will include:

• total: Total number of locations matching the string provided. If this is greater than the number of locations listed in the locations field, it indicates that there are more matches than returned in the current results.
• locations: A list of up to 10 matching locations. For each location provided, we will return:
  • uuid: A universally unique ID for the location, which can be used to retrieve stories about that location in our Stories Query Resource.
  • display_name: User-friendly name for the location. 
  • url_name: URL-friendly name for the location.
  • city: The name of the city that contains the location, if any.
  • state: The name of the state that contains the location, if any.
  • state_abbrev: The two-character postal abbreviation for the state that contains the location, if any.
  • url: The Outside.in permalink for stories about the requested location. This is useful for linking your users to more results.
  • category: Information about the type of location requested, including:
    • display_name: User-friendly name for the type of location. 
    • name: URL-friendly name for the type of location.
  • lat: The latitude of the centroid of the location.
  • lng: The longitude of the centroid of the location.

Exceptions

No Name Parameter

If no "name" parameter is included in a locations query, we will return a 400 error.

No Matching Locations Found

If no locations match the name parameter provided, the "total" field will have a value of 0 and the "locations" field will be empty.

Other Exceptions

Get more information about HTTP status codes you may encounter in the Documentation Overview.

Parameters

Location Category

By default, we will return any states, cities, ZIP codes, or neighborhoods matching the name provided. You can specify that you would only like to see one or more type(s) of locations in your results by appending a limit parameter to your locations request formatted as follows:

&category={category name}
&category={category name}&category={category name} 

You must provide one of the following category names for this parameter to work:

• state
• city (This will return only cities, towns, or villages matching your request.)
• postal_code (This will return only ZIP codes matching your request.)
• neighborhood
• locality (This will return only the five boroughs of New York City matching your request.)
• named_place (This will only return places of interest, such as businesses, landmarks, and parks.)
• metro (This will return only metro areas matching your request.)
• sub_metro (This will return only sub-metro areas matching your request. Sub-metro areas are currently only available in the Chicagoland Metro Area.)
• district (This will return only districts and counties matching your request.)

For example:

&category=neighborhood
&category=neighborhood&category=city 

Limit

By default, we will return a maximum of 10 locations matching the name provided. You can adjust this maximum by appending a limit parameter to your locations request formatted as follows:

&limit={integer}

You must provide an integer between 1 and 100 for this parameter to work. For example:

&limit=50