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

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.

Example Values: 37.7821120598956

long required

The longitude to search around. The valid ranges for longitude is -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 disabled, or if there not a corresponding lat parameter.

Example Values: -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.).

Example Values: 5ft

granularity optional

This is the minimal granularity of place types to return and must be one of: poi, 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.

Example Values: 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.

Example Values: 3

callback optional

If supplied, the response will use the JSONP format with a callback of the given name.

OAuth Signature Generator

Sign in to see a list of your registered applications.

Example Request

GET

https://api.twitter.com/1.1/geo/reverse_geocode.json?lat=37.76893497&long=-122.42284884

Example Result

{
  "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"
      }
    ]
  }
}