GET geo/reverse_geocode
get-geo-reverse_geocode

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.x.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.x.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.x.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.x.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.x.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.x.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.x.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.x.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.x.com/1.1/geo/id/96683cc9126741d1.json"
      }
    ]
  }
}