Get places near a location

API reference contents

GET geo/reverse_geocode

Given a latitude and a longitude, searches for up to 20 places that can be used as a place_id when updating a status.

This request is an informative call and will deliver generalized results about geography.

Resource URL

https://api.twitter.com/1.1/geo/reverse_geocode.json

Resource Information

Response formats JSON
Requires authentication? Yes (user context only)
Rate limited? Yes
Requests / 15-min window (user auth) 15

Parameters

Name Required Description Default Value Example
lat required The latitude to search around. This parameter will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding long parameter. 37.7821120598956
long required The longitude to search around. The valid ranges for longitude are -180.0 to +180.0 (East is positive) inclusive. This parameter will be ignored if outside that range, if it is not a number, if geo_enabled is turned off, or if there not a corresponding lat parameter. -122.400612831116
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.). 0m 500ft
granularity optional

This is the minimal granularity of place types to return and must be one of: neighborhood, city, admin or country . If no granularity is provided for the request neighborhood is assumed.

Setting this to city, for example, will find places which have a type of city, admin or country.

neighborhood city
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. 3

Example Request

twurl '/1.1/geo/reverse_geocode.json?lat=37.781157&long=-122.398720&granularity=neighborhood'

Example Response

{
  "query": {
    "params": {
      "accuracy": 0,
      "coordinates": {
        "coordinates": [
          -122.42284884,
          37.76893497
        ],
        "type": "Point"
      },
      "granularity": "neighborhood"
    },
    "type": "reverse_geocode",
    "url": "https://api.twitter.com/1.1/geo/reverse_geocode.json?accuracy=0&granularity=neighborhood&lat=37.76893497&long=-122.42284884"
  },
  "result": {
    "places": [
      {
        "attributes": {},
        "bounding_box": {
          "coordinates": [
            [
              [
                -122.42676492,
                37.75983003
              ],
              [
                -122.420736,
                37.75983003
              ],
              [
                -122.420736,
                37.77226299
              ],
              [
                -122.42676492,
                37.77226299
              ]
            ]
          ],
          "type": "Polygon"
        },
        "contained_within": [
          {
            "attributes": {},
            "bounding_box": {
              "coordinates": [
                [
                  [
                    -122.51368188,
                    37.70813196
                  ],
                  [
                    -122.35845384,
                    37.70813196
                  ],
                  [
                    -122.35845384,
                    37.83245301
                  ],
                  [
                    -122.51368188,
                    37.83245301
                  ]
                ]
              ],
              "type": "Polygon"
            },
            "country": "United States",
            "country_code": "US",
            "full_name": "San Francisco, CA",
            "id": "5a110d312052166f",
            "name": "San Francisco",
            "place_type": "city",
            "url": "https://api.twitter.com/1.1/geo/id/5a110d312052166f.json"
          }
        ],
        "country": "United States",
        "country_code": "US",
        "full_name": "Mission Dolores, San Francisco",
        "id": "cf7afb4ee6011bca",
        "name": "Mission Dolores",
        "place_type": "neighborhood",
        "url": "https://api.twitter.com/1.1/geo/id/cf7afb4ee6011bca.json"
      },
      {
        "attributes": {},
        "bounding_box": {
          "coordinates": [
            [
              [
                -122.51368188,
                37.70813196
              ],
              [
                -122.35845384,
                37.70813196
              ],
              [
                -122.35845384,
                37.83245301
              ],
              [
                -122.51368188,
                37.83245301
              ]
            ]
          ],
          "type": "Polygon"
        },
        "contained_within": [
          {
            "attributes": {},
            "bounding_box": {
              "coordinates": [
                [
                  [
                    -124.482003,
                    32.528832
                  ],
                  [
                    -114.131211,
                    32.528832
                  ],
                  [
                    -114.131211,
                    42.009517
                  ],
                  [
                    -124.482003,
                    42.009517
                  ]
                ]
              ],
              "type": "Polygon"
            },
            "country": "United States",
            "country_code": "US",
            "full_name": "California, US",
            "id": "fbd6d2f5a4e4a15e",
            "name": "California",
            "place_type": "admin",
            "url": "https://api.twitter.com/1.1/geo/id/fbd6d2f5a4e4a15e.json"
          }
        ],
        "country": "United States",
        "country_code": "US",
        "full_name": "San Francisco, CA",
        "id": "5a110d312052166f",
        "name": "San Francisco",
        "place_type": "city",
        "url": "https://api.twitter.com/1.1/geo/id/5a110d312052166f.json"
      },
      {
        "attributes": {},
        "bounding_box": {
          "coordinates": [
            [
              [
                -124.482003,
                32.528832
              ],
              [
                -114.131211,
                32.528832
              ],
              [
                -114.131211,
                42.009517
              ],
              [
                -124.482003,
                42.009517
              ]
            ]
          ],
          "type": "Polygon"
        },
        "contained_within": [
          {
            "attributes": {},
            "bounding_box": null,
            "country": "United States",
            "country_code": "US",
            "full_name": "United States",
            "id": "96683cc9126741d1",
            "name": "United States",
            "place_type": "country",
            "url": "https://api.twitter.com/1.1/geo/id/96683cc9126741d1.json"
          }
        ],
        "country": "United States",
        "country_code": "US",
        "full_name": "California, US",
        "id": "fbd6d2f5a4e4a15e",
        "name": "California",
        "place_type": "admin",
        "url": "https://api.twitter.com/1.1/geo/id/fbd6d2f5a4e4a15e.json"
      },
      {
        "attributes": {},
        "bounding_box": null,
        "contained_within": [],
        "country": "United States",
        "country_code": "US",
        "full_name": "United States",
        "id": "96683cc9126741d1",
        "name": "United States",
        "place_type": "country",
        "url": "https://api.twitter.com/1.1/geo/id/96683cc9126741d1.json"
      }
    ]
  }
}

Was this document helpful?

Thank you

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?

Thank you for the feedback. Your comments will help us improve our documents in the future.