Find Stories by Location

Our Stories Query Resource allows you to request stories for any location in the U.S. by state, city, ZIP code, neighborhood, or Patch location UUID.  

Requests

State

To retrieve stories for any U.S. state, send a GET request to our Stories Query Resource formated as follows:

http://news-api.patch.com/v1.1/states/{state abbreviation}/stories?dev_key={key}&sig={signature}
http://news-api.patch.com/v1.1/states/{state name}/stories?dev_key={key}&sig={signature}

For example, both of these queries will return the 10 most recent stories in Florida within the past 10 days:

http://news-api.patch.com/v1.1/states/fl/stories?dev_key={key}&sig={signature}
http://news-api.patch.com/v1.1/states/florida/stories?dev_key={key}&sig={signature}

Inputs for state name and abbreviation are case-insensitive.

City

To retrieve stories for any U.S. city, send a GET request to our Stories Query Resource formated as follows:

http://news-api.patch.com/v1.1/states/{state abbreviation}/cities/{city name}/stories?dev_key={key}&sig={signature}
http://news-api.patch.com/v1.1/states/{state name}/cities/{city name}/stories?dev_key={key}&sig={signature} 

For example, either of these queries will return the 10 most recent stories in San Francisco, CA within the past 10 days:

http://news-api.patch.com/v1.0/states/ca/cities/san%20francisco/stories?dev_key={key}&sig={signature}
http://news-api.patch.com/v1.0/states/california/cities/san%20francisco/stories?dev_key={key}&sig={signature} 

Inputs for state name, state abbreviation, and city name are case-insensitive.

ZIP Code

To retrieve stories for any U.S. ZIP code, send a GET request to our Stories Query Resource formated as follows:

http://news-api.patch.com/v1.1/zipcodes/{ZIP}/stories?dev_key={key}&sig={signature}

For example, this query will return the 10 most recent stories in 11215 within the past 10 days:

http://news-api.patch.com/v1.1/zipcodes/11215/stories?dev_key={key}&sig={signature}

Neighborhood

To retrieve stories for any U.S. neighborhood, send a GET request to our Stories Query Resource formated as follows:

http://news-api.patch.com/v1.1/states/{state abbreviation}/cities/{city name}/nabes/{neighborhood name}/stories?dev_key={key}&sig={signature}
http://news-api.patch.com/v1.1/states/{state name}/cities/{city name}/nabes/{neighborhood name}/stories?dev_key={key}&sig={signature} 

For example, either of these queries will return the 10 most recent stories in Downtown Los Angeles within the past 10 days:

http://news-api.patch.com/v1.1/states/ca/cities/los%20angeles/nabes/downtown/stories?dev_key={key}&sig={signature}
http://news-api.patch.com/v1.1/states/california/cities/los%20angeles/nabes/downtown/stories?dev_key={key}&sig={signature}

Inputs for state name, state abbreviation, city name, and neighborhood name are case-insensitive.

Nearby

To retrieve stories within 1,000 feet of any latitude and longitude in the U.S., send a GET request to our Stories Query Resource formatted as follows:

http://news-api.patch.com/v1.1/nearby/{latitude},{longitude}/stories?dev_key={key}&sig={signature}

For example, this query will return the 10 most recent stories within 1,000 feet of former Outside.in HQ (22 West 21st Street, New York, NY):

http://news-api.patch.com/v1.1/nearby/40.740512,-73.991479/stories?dev_key={key}&sig={signature}

If you need a way to get lat/lngs for addresses, try the Google Geocoding API or the Yahoo! Geocoding API, which has a nice interface here.

You can adjust the radius within which you receive stories using the radius parameter.

Patch Location UUID

Single UUID

To retrieve stories for exactly one U.S. state, city, ZIP code, or neighborhood by Patch UUID, send a GET request to our Stories Query Resource formated as follows:

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

For example, this query will return the 10 most recent stories in 11215 within the past 10 days:

http://news-api.patch.com/v1.1/locations/428090d4-759e-4a05-b060-af357a589890/stories?dev_key={key}&sig={signature}

Multiple UUIDs

To retrieve stories for multiple U.S. state, city, ZIP code, or neighborhood by Patch UUID, send a GET request to our Stories Query Resource formated as follows:

http://news-api.patch.com/v1.0/locations/{UUID},{UUID},{UUID}/stories?dev_key={key}&sig={signature}

For example, this query will return the 10 most recent stories that mention locations in 11215, San Francisco, or Florida within the past 10 days:

http://news-api.patch.com/v1.0/locations/428090d4-759e-4a05-b060-af357a589890,9f119294-bb7d-4645-8e1f-75c62214503d,c4c208ed-7576-4711-8fe4-69c26b618872/stories?dev_key={key}&sig={signature}

You may request stories from up to five locations in this format.

Finding UUIDs

You can find the UUIDs you need to make these queries using our Locations Query Resource, which allows you to query for locations (including states, cities, ZIPs, neighborhoods, metro areas, sub-metro areas, and districts) by name.

Results

The results for requests for any valid U.S. state, city, ZIP code, or neighborhood or any single valid Patch UUID will include:

• total: Total number of stories in the location requested in the past 10 days. This number may be greater than the number of stories provided in the stories field, which indicates that there are more stories available for your query than are returned in the current results.
• stories: Up to 10 most recent stories in the location requested within the past 10 days. For each story we will provide:
  • uuid: A universally unique ID for the story.
  • title: Title of the story.
  • summary: First 200 characters of the story.
  • story_url: Permalink to the story on the website of the original source. The story_url is routed through an Outside.in/Patch redirect, which may not be stripped out.
  • feed_title: The name of the feed from which the story was found.
  • feed_url: The homepage for the original publisher of the story.
  • tags:  All topic tags associated with the story.
  • source_verticals: All verticals attached to the feed or feeds from which we found the story.
  • source_author_types: All author types attached to the feed or feeds from which we found the story.
  • source_formats: All formats attached to the feed or feeds from which we found the story.
  • published_at: The timestamp at which the story was published in the source feed.
• location: All results to the Stories Query Resource except for Nearby Queries will include metadata about the location requested, including:
  • uuid: A universally unique ID for the location.
  • 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/Patch 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.
• links: A list of links to queries that use the page parameter to retrieve other sets of results matching the query, if there are more results than 10 (or the number specified in the limit parameter). This list may include:
  • first: The first set of results matching the query.
  • last: The last set of results matching the query.
  • next: The next set of results matching the query.
  • previous: The previous set of results matching the query.

Results for Nearby Queries will include an additional field called "nearby" that has the following data points:

• lat: the latitude requested
• lng: the longitude requested
• radius: the radius requested in feet

If you have requested multiple locations by their UUIDs, the location field will be returned as a list that includes metadata about all locations requested.

Exceptions

If the specified location is not a valid U.S. state, city, ZIP code, neighborhood, or Patch UUID, a 404 error will be returned. Get more information about HTTP status codes you may encounter in the Documentation Overview.

No News is Good News

If there are no stories matching your request, we'll return a 200 response with location metadata, a count of zero, and an empty set of stories.

Parameters

Limit

By default, we will return a maximum of 10 stories in the location requested. You can adjust this maximum by appending a limit parameter to your story request formatted as follows:

&limit={integer}

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

&limit=50

Max Age

By default, we will return stories posted within the past 10 days. You can adjust the age of stories we return by appending a max_age parameter to your story request formatted as follows:

&max_age={integer}d

The only accepted unit is days. The minimum max_age is 1 day and the maximum is 30 days.

Here are some examples of properly formatted max_age parameters:

&max_age=9d
&max_age=1d  

Keyword

Include

To limit the stories in your results to only those including one or more words or phrases, append the following parameter to your request:

&keyword={string}
&keyword={string}&keyword={string}&keyword={string} 

For example, adding the following to your request will limit the stories in your results to only those including the word "art" in the story title, story summary, or topic tags:

&keyword=art

These parameters will limit the stories in your results to only those including the word "crime" OR the exact phrase "police reports" in the story title, story summary, or topic tags:

&keyword=crime&keyword=police%20reports

Note that including multiple keywords with &keyword provides results for a search for all specified search terms joined by an OR. To get results for multiple search terms joined by an AND, use the following parameter:

&all-keyword={string}&all-keyword={string}

For example, adding the following to your request will limit the stories in your results to only those including the word "crime" AND the exact phrase "police reports" in the story title, story summary, or topic tags:

&all-keyword=crime&all-keyword=police%20reports

Exclude

To limit the stories in your results to only those that DO NOT include one or more words or phrases, append the following parameter to your request:

&no-keyword={string}
&no-keyword={string}&no-keyword={string}&no-keyword={string} 

For example, adding the following to your request will limit the stories in your results to only those that do not have the word "art" in the story title, story summary, or topic tags:

&no-keyword=art

These parameters will limit the stories in your results to only those that do not have the word "crime" OR the exact phrase "police reports" in the story title, story summary, or topic tags:

&no-keyword=crime&no-keyword=police%20reports

Vertical

Vertical is one component of a three-part taxonomy that we use to organize the source feeds from which we aggregate stories. Vertical provides information about the topic of the feed, such as "News" or "Sports." Check out our complete list of Source Taxonomy Values to find out what values you can use for Vertical parameters.

Include

To limit the stories in your results to only those from feeds with one or more specific Verticals, append the following parameter to your request:

&vertical={vertical name}
&vertical={vertical name}&vertical={vertical name}&vertical={vertical name} 

For example, adding the following to your request will limit the stories in your results to only those from source feeds that we have labeled as publishing stories about "Crime":

&vertical=crime

These parameters will limit the stories in your results to only those from source feeds that we have labeled as publishing stories about "Crime" OR "Politics":

&vertical=crime&vertical=politics

Exclude

To limit the stories in your results to only those that ARE NOT from sources with one or more specific Verticals, append the following parameter to your request:

&no-vertical={vertical name}
&no-vertical={vertical name}&no-vertical={vertical name}&no-vertical={vertical name} 

For example, adding the following to your request will limit the stories in your results to only those that are not from feeds labeled as publishing stories about "Crime":

&no-vertical=crime

This parameter will limit the stories in your results to only those that are not from feeds labeled as publishing stories about "Crime" or "Politics":

&no-vertical=crime&no-vertical=politics

Format

Format is another component of a three-part taxonomy that we use to organize the source feeds from which we aggregate stories. Format provides information about the medium of content that the feed publishes, such as "Blog Posts," "News Articles," or "Reviews and Ratings." Check out our complete list of Source Taxonomy Values to find out what values you can use for Format parameters.

Include

To limit the stories in your results to only those from feeds with one or more specific Formats, append the following parameter to your request:

&format={format name}
&format={format name}&format={format name}&format={format name} 

For example, adding the following to your request will limit the stories in your results to only those from source feeds that we have labeled as publishing "Blog Posts":

&format=blog-posts

These parameters will limit the stories in your results to only those from source feeds that we have labeled as being publishing "Blog Posts" or "Municipal Data":

&format=blog-posts&format=news-articles

Exclude

To limit the stories in your results to only those that ARE NOT from sources with one or more specific Formats, append the following parameter to your request:

&no-format={format name}
&no-format={format name}&no-format={format name}&no-format={format name} 

For example, adding the following to your request will limit the stories in your results to only those that are not from feeds labeled as Publishing "Blog Posts":

&no-format=blog-posts

This parameter will limit the stories in your results to only those that are not from feeds labeled as publishing "Blog Posts" or "Municipal Data":

&no-format=blog-posts&no-format=news-articles

Author Type

Author Type is the final component of a three-part taxonomy that we use to organize the source feeds from which we aggregate stories. Author Type provides information about the type of author that publishes the feed, such as "Individuals" (for regular folks' blog posts) or "Mainstream Media" (for blog posts or news stories published by major publications). Check out our complete list of Source Taxonomy Values to find out what values you can use for Author Type parameters.

Include

To limit the stories in your results to only those from feeds with one or more specific Author Types, append the following parameter to your request:

&author-type={author type name}
&author-type={author type name}&author-type={author type name}&author-type={author type name} 

For example, adding the following to your request will limit the stories in your results to only those from source feeds that we have labeled as being published by "Individuals":

&author-type=individuals

These parameters will limit the stories in your results to only those from source feeds that we have labeled as being published by "Individuals" OR "Organizations":

&author-type=individuals&author-type=organizations

Exclude

To limit the stories in your results to only those that ARE NOT from sources with one or more specific Author Types, append the following parameter to your request:

&no-author-type={author type name}
&no-author-type={author type name}&no-author-type={author type name}&no-author-type={author type name} 

For example, adding the following to your request will limit the stories in your results to only those that are not from feeds labeled as being published by "Individuals":

&no-author-type=individuals

This parameter will limit the stories in your results to only those that are not from feeds labeled as being published by "Individuals" OR "Organizations":

&no-author-type=individuals&no-author-type=organizations

Include Locations

To see all the locations attached to each story in your results, append the following parameter to your request:

&include-locations=true

For each location attached to stories, we'll show the following information:

• uuid: A universally unique ID for the location.
• display_name: User-friendly name for the location.
• url_name: URL-friendly name for the location. 
• street_address: The street address of the location (places only).
• 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/Patch 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 for regions, or the exact latitude of the location for places.
• lng: The longitude of the centroid of the location, or the exact longitude of the location for places.
• hot_for_requested: A true/false indication of whether the location is "hot" in the region for which you requested stories. "Hot" means that it is one of the top 20 story-producting locations in the region you requested.

Places Only

To limit the stories in your results to those attached to specific places (like landmarks or places of business instead of regions like ZIP codes or cities), append the following parameter to your request:

&places-only=true

Page

To retrieve an additional set of results for any query, append the following parameter to your request:

&page={page number}

The number provided must be an integer. For example:

&page=2

Whether or not you'll see results in any given page of results depends upon how many results are available matching the rest of your query. All queries for which additional pages of results are available will include a "links" field in the results that lists queries for relevant pages of results for the same request (first, last, next, and previous).

Radius (Nearby Queries Only)

To adjust the radius within which you receive stories in a Nearby Query, append the following parameter to your request:

&radius={radius in feet}

You must provide an integer between 500 and 26,400 to use this parameter. For example:

&radius=10000
&radius=501