<< Back to Twitter API Documentation

 

Twitter REST API Method: geo/nearby_places

Search for places (cities and neighborhoods) that can be attached to a statuses/update.  Given a latitude and a longitude pair, or an IP address, return a list of all the valid cities and neighborhoods that can be used as a place_id when updating a status.  Conceptually, a query can be made from the user's location, retrieve a list of places, have the user validate the location he or she is at, and then send the ID of this location up with a call to statuses/update.

 

There are multiple granularities of places that can be returned -- "neighborhoods", "cities", etc.  At this time, only United States data is available through this method.  

 

This is the recommended method to use find places that can be attached to statuses/update.  Unlike geo/reverse_geocode which provides raw data access, this endpoint can potentially re-order places with regards to the user who is authenticated.

method status | report a bug 

URL:

http://api.twitter.com/1/geo/nearby_places.json

 

Formats: 

json

 

HTTP Method(s):

GET

 

Requires Authentication (about authentication):

false but authentication is recommended so as to provide a preferential sort for the user

 

API rate limited (about rate limiting):

true

 

Parameters:

• lat.  Optional but required if long provided or if ip is not provided.  The latitude to query about.  Valid ranges are -90.0 to +90.0 (North is positive) inclusive.
• long. Optional but required if lat provided or if ip is not provided. The longitude to query about.  Valid ranges are -180.0 to +180.0 (East is positive) inclusive.
• ip. Optional but required if lat and long are not provided.  The IP address that the call is coming from. Twitter will geo-IP the address.
• accuracy. Optional. A hint on the "region" in which to search.  If a number, then this is a radius in meters, but it can also take a string that is suffixed with ft to specify feet.  If this is not passed in, then it is assumed to be 0m.  If coming from a device, in practice, this value is whatever accuracy the device has measuring its location (whether it be coming from a GPS, WiFi triangulation, etc.).
• granularity. Optional.  The minimal granularity of data to return.  If this is not passed in, then neighborhood is assumed.  city can also be passed.
• max_results. Optional.  A hint as to the number of results to return.  This does not guarantee that the number of results returned will equal max_results, but instead informs how many "nearby" results to return.  Ideally, only pass in the number of places you intend to display to the user here.

   

Abbreviated Response (about return values):  

{

  "query": {

    "type":"reverse_geocode",

    "url":"/1/geo/reverse_geocode.json?lat=37.78215&long=-122.40060&accuracy=0&granularity=neighborhood",

    "params": {

      "granularity":"neighborhood",

      "coordinates": {

        "type":"Point",

        "coordinates":[-122.40060,37.78215]

      },

      "accuracy":0

    }

  },

  "result": {

    "places": [

      {

        "name":"SoMa",

        "country_code":"US",

        "id":"7695dd2ec2f86f2b",

        "country":"United States",

        "place_type":"neighborhood",

        "url":"/1/geo/id/7695dd2ec2f86f2b.json",

        "full_name":"SoMa,

         San Francisco",

        "bounding_box": {

            "type":"Polygon",

            "coordinates": [

              [ [-122.42284884, 37.76893497],

                [-122.3964, 37.76893497],

                [-122.3964, 37.78752897],

                [-122.42284884, 37.78752897] ]

            ]

        },

        "contained_within": [

          {

            "place_type":"city",

            "url":"/1/geo/id/6f165220310d115a.json",

            "bounding_box": {

              "type":"Polygon",

              "coordinates": [

                [ [-123.173825, 37.63983],

                  [-122.28178, 37.63983],

                  [-122.28178, 37.929824],

                  [-123.173825, 37.929824] ]

              ]

            },

            "full_name":"San Francisco,CA",

            "country_code":"US",

            "name":"San Francisco",

            "id":"6f165220310d115a",

            "country":"United States"

          }

        ]

      }

    ]

    ...

  }

}

 

Usage examples: 

cURL (about cURL):

curl "http://api.twitter.com/1/geo/reverse_geocode.json?lat=37.78215&long=-122.40060"

 

          Do you have an example to share in the language of your choice? Please share!