Overview

The outside.in API lets you easily integrate hyperlocal news in your own applications. This means that you give us a specific location and we give you back all of the recent news stories, blog posts, twitter Tweets and more happening around that point, for any distance from 1,000 feet all the way up to 2 miles. No API key is required, and we've kept our Terms of Service very simple.

This is just the first, simple offering of our API—we're already working on extending the functionality and will have new releases out soon. If you have any feedback or suggested additions, please let us know in the Outside.in API Google Group.

Get Started

• Watch a video of our developers explaining the API.
• Read the blog post introducing the API.
• Check out near.ly, a site built with our API.
• Talk to other developers in the outside.in API Google Group.
• Suggest an application you think should be built with our API.

Documentation

Our API returns blog posts, newspaper articles, tweets, and outside.in discussion posts geolocated around the latitude and longitude requested, for any distance from 1,000 feet all the way up to 2 miles.

Formats

The outside.in API is available in JSON and XML.

XML

You can grab our hyperlocal news around any lat/lng as an XML feed. For example, this is the XML feed for 40.705563, -73.986762 (that's the lat/lng for Times Square!). To request search results in XML, append your URL-encoded lat/lng as a parameter to the latitude and longitude methods and specify the XML format:

http://api.outside.in/radar.xml?lat=<latitude>&lng=<longitude>

JSON

You can also request our API results in JSON. For example, this is the JSON response for 40.705563, -73.986762. To request search results in JSON, append your URL-encoded lat/lng as a parameter to the search method and specify the JSON format:

http://api.outside.in/radar.json?lat=<latitude>&lng=<longitude>

Results

Our API returns in its results stories (blog posts and news stories), Tweets (from Twitter), and remarks from outside.in discussion boards. The 10 most recent items are returned in reverse-chronological order.

Stories

For blog posts and news stories, the API returns the following fields:

• item_id: the number that identifies the story in our database
• icon_path: the path to http://outside.in/images/radar_icons/news.png, which we use on our site to differentiate stories from other content (such as Tweets or discussion posts)
• author: the title of the blog or website that published the story
• author_url: the URL of the blog or website that published the story
• published_at: the story's time stamp
• title: the story's title
• body: the first 300 characters of the story
• url: the URL of the original story

We also return the tags and places that we've attached to each story. For each tag, we return:

• name: the name of the tag
• url: our page for that tag in the neighborhood that the story is about (e.g. http://outside.in/DUMBO_Brooklyn_NY/tags/food for the tag "food" in DUMBO)

And for each place, we'll give you:

• id: the number that identifies the place in our database
• name: the name of the place
• url: our page for that place (e.g. http://outside.in/places/american-museum-of-natural-history for the Museum of Natural History)
• georss:point the latitude and longitude of the place

Tweets

For Tweets, the API returns the following fields:

• item_id: the number that identifies the tweet in our database
• icon_path: the path to http://outside.in/images/radar_icons/tweet.png, which we use on our site to differentiate Tweets from other content (such as blog posts or discussion posts)
• author: the Twitter username of the tweet's author
• author_url: the URL of the author's Twitter feed
• published_at: the Tweet's timestamp
• body: the full text of the Tweet
• url: the URL of the original Tweet
• image_url: the path tho the author's Twitter avatar

We also return the places that we've attached to each Tweet. For each place, we'll give you:

• id: the number that identifies the place in our database
• name: the name of the place
• url: our page for that place (e.g.http://outside.in/places/american-museum-of-natural-history for the Museum of Natural History)
• georss:point: the latitude and longitude of the place

Remarks

For remarks made on outside.in discussion boards, the API returns the following fields:

• item_id: the number that identifies the remark in our database
• icon_path: the path to http://outside.in/images/radar_icons/comment.png, which we use on our site to differentiate discussion board posts from other content (such as blog posts or tweets)
• author: the outside.in username of the user who made the post
• author_url: the URL of the user's outside.in profile
• published_at: the timestamp of the discussion post
• title: the title of the discussion post
• body: the full text of the discussion post
• url: the URL of the discussion thread
• image_url: the path to the user's outside.in profile photo

We also return the places that we've attached to each remark. For each place, we'll give you:

• id: the number that identifies the place in our database
• name: the name of the place
• url: our page for that place (e.g. http://outside.in/places/american-museum-of-natural-history for the Museum of Natural History)
• georss:point: the latitude and longitude of the place

Parameters

The following parameters can be applied to further refine the results returned by our API.

Radius

The default radius for our API results is 1,000 feet, which provides news around the block for any urban location.

You can also request results for a custom radius up to two miles by attaching radius as a parameter to the end of your API request URL:

http://api.outside.in/radar.xml?lat=<latitude>&lng=<longitude>&radius=<radius>

http://api.outside.in/radar.json?lat=<latitude>&lng=<longitude>&radius=<radius>

For example, this is the XML feed for news stories, blog posts, Twitter tweets, and discussion board remarks within one mile of 40.705563, -73.986762.

The radius parameter accepts decimals, so you can request specific ranges. Any entry greater than two will simply return results within two miles of the given latitude and longitude.

Only

If you only want to see certain types of results, you can apply only as a parameter on your API request URL:

http://api.outside.in/radar.xml?lat=<latitude>&lng=<longitude>&only=<item_type>

http://api.outside.in/radar.json?lat=<latitude>&lng=<longitude>&only=<item_type>

For example, this XML feed returns only stories (which includes blog posts and news articles) within 1,000 feet of 40.705563, -73.986762, and this XML feed returns both stories and Tweets within 1,000 feet of 40.705563, -73.986762.

Possible values for the only parameter are stories, tweets, and remarks.

Except

Similarly, if you want to exclude certain types of results, you can apply except as a parameter on your API request URL:

http://api.outside.in/radar.xml?lat=<latitude>&lng=<longitude>&except=<item_type>

http://api.outside.in/radar.json?lat=<latitude>&lng=<longitude>&except=<item_type>

For example, this XML feed returns all results except Tweets within 1,000 feet of 40.705563, -73.986762, and this XML feed returns all results except remarks or Tweets within 1,000 feet of 40.705563, -73.986762.

Possible values for the except parameter are stories, tweets, and remarks.

Terms of Service

outside.in welcomes all uses of our API. We have only a few rules that we ask you to follow:

1. If you display content that comes from our API, please credit us by linking back to outside.in. If you'd like, you can even use this badge:

2. We limit total daily requests per application to 30,000. If you find yourself going over that number, please let us know to discuss your needs.

3. We reserve the rights to change these terms of service at any time.

4. Finally, if you use our API please let us know so we can tell people about what you built.