GET geo/reverse_geocode

API version 1.1
Updated on Tue, 2013-04-23 07:27

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

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.

Example Request

GET

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

  1. {
  2.   "query": {
  3.     "params": {
  4.       "accuracy": 0, 
  5.       "coordinates": {
  6.         "coordinates": [
  7.           -122.42284884, 
  8.           37.76893497
  9.         ], 
  10.         "type": "Point"
  11.       }, 
  12.       "granularity": "neighborhood"
  13.     }, 
  14.     "type": "reverse_geocode", 
  15.     "url": "https://api.twitter.com/1.1/geo/reverse_geocode.json?accuracy=0&granularity=neighborhood&lat=37.76893497&long=-122.42284884"
  16.   }, 
  17.   "result": {
  18.     "places": [
  19.       {
  20.         "attributes": {}, 
  21.         "bounding_box": {
  22.           "coordinates": [
  23.             [
  24.               [
  25.                 -122.42676492, 
  26.                 37.75983003
  27.               ], 
  28.               [
  29.                 -122.420736, 
  30.                 37.75983003
  31.               ], 
  32.               [
  33.                 -122.420736, 
  34.                 37.77226299
  35.               ], 
  36.               [
  37.                 -122.42676492, 
  38.                 37.77226299
  39.               ]
  40.             ]
  41.           ], 
  42.           "type": "Polygon"
  43.         }, 
  44.         "contained_within": [
  45.           {
  46.             "attributes": {}, 
  47.             "bounding_box": {
  48.               "coordinates": [
  49.                 [
  50.                   [
  51.                     -122.51368188, 
  52.                     37.70813196
  53.                   ], 
  54.                   [
  55.                     -122.35845384, 
  56.                     37.70813196
  57.                   ], 
  58.                   [
  59.                     -122.35845384, 
  60.                     37.83245301
  61.                   ], 
  62.                   [
  63.                     -122.51368188, 
  64.                     37.83245301
  65.                   ]
  66.                 ]
  67.               ], 
  68.               "type": "Polygon"
  69.             }, 
  70.             "country": "United States", 
  71.             "country_code": "US", 
  72.             "full_name": "San Francisco, CA", 
  73.             "id": "5a110d312052166f", 
  74.             "name": "San Francisco", 
  75.             "place_type": "city", 
  76.             "url": "https://api.twitter.com/1.1/geo/id/5a110d312052166f.json"
  77.           }
  78.         ], 
  79.         "country": "United States", 
  80.         "country_code": "US", 
  81.         "full_name": "Mission Dolores, San Francisco", 
  82.         "id": "cf7afb4ee6011bca", 
  83.         "name": "Mission Dolores", 
  84.         "place_type": "neighborhood", 
  85.         "url": "https://api.twitter.com/1.1/geo/id/cf7afb4ee6011bca.json"
  86.       }, 
  87.       {
  88.         "attributes": {}, 
  89.         "bounding_box": {
  90.           "coordinates": [
  91.             [
  92.               [
  93.                 -122.51368188, 
  94.                 37.70813196
  95.               ], 
  96.               [
  97.                 -122.35845384, 
  98.                 37.70813196
  99.               ], 
  100.               [
  101.                 -122.35845384, 
  102.                 37.83245301
  103.               ], 
  104.               [
  105.                 -122.51368188, 
  106.                 37.83245301
  107.               ]
  108.             ]
  109.           ], 
  110.           "type": "Polygon"
  111.         }, 
  112.         "contained_within": [
  113.           {
  114.             "attributes": {}, 
  115.             "bounding_box": {
  116.               "coordinates": [
  117.                 [
  118.                   [
  119.                     -124.482003, 
  120.                     32.528832
  121.                   ], 
  122.                   [
  123.                     -114.131211, 
  124.                     32.528832
  125.                   ], 
  126.                   [
  127.                     -114.131211, 
  128.                     42.009517
  129.                   ], 
  130.                   [
  131.                     -124.482003, 
  132.                     42.009517
  133.                   ]
  134.                 ]
  135.               ], 
  136.               "type": "Polygon"
  137.             }, 
  138.             "country": "United States", 
  139.             "country_code": "US", 
  140.             "full_name": "California, US", 
  141.             "id": "fbd6d2f5a4e4a15e", 
  142.             "name": "California", 
  143.             "place_type": "admin", 
  144.             "url": "https://api.twitter.com/1.1/geo/id/fbd6d2f5a4e4a15e.json"
  145.           }
  146.         ], 
  147.         "country": "United States", 
  148.         "country_code": "US", 
  149.         "full_name": "San Francisco, CA", 
  150.         "id": "5a110d312052166f", 
  151.         "name": "San Francisco", 
  152.         "place_type": "city", 
  153.         "url": "https://api.twitter.com/1.1/geo/id/5a110d312052166f.json"
  154.       }, 
  155.       {
  156.         "attributes": {}, 
  157.         "bounding_box": {
  158.           "coordinates": [
  159.             [
  160.               [
  161.                 -124.482003, 
  162.                 32.528832
  163.               ], 
  164.               [
  165.                 -114.131211, 
  166.                 32.528832
  167.               ], 
  168.               [
  169.                 -114.131211, 
  170.                 42.009517
  171.               ], 
  172.               [
  173.                 -124.482003, 
  174.                 42.009517
  175.               ]
  176.             ]
  177.           ], 
  178.           "type": "Polygon"
  179.         }, 
  180.         "contained_within": [
  181.           {
  182.             "attributes": {}, 
  183.             "bounding_box": null, 
  184.             "country": "United States", 
  185.             "country_code": "US", 
  186.             "full_name": "United States", 
  187.             "id": "96683cc9126741d1", 
  188.             "name": "United States", 
  189.             "place_type": "country", 
  190.             "url": "https://api.twitter.com/1.1/geo/id/96683cc9126741d1.json"
  191.           }
  192.         ], 
  193.         "country": "United States", 
  194.         "country_code": "US", 
  195.         "full_name": "California, US", 
  196.         "id": "fbd6d2f5a4e4a15e", 
  197.         "name": "California", 
  198.         "place_type": "admin", 
  199.         "url": "https://api.twitter.com/1.1/geo/id/fbd6d2f5a4e4a15e.json"
  200.       }, 
  201.       {
  202.         "attributes": {}, 
  203.         "bounding_box": null, 
  204.         "contained_within": [], 
  205.         "country": "United States", 
  206.         "country_code": "US", 
  207.         "full_name": "United States", 
  208.         "id": "96683cc9126741d1", 
  209.         "name": "United States", 
  210.         "place_type": "country", 
  211.         "url": "https://api.twitter.com/1.1/geo/id/96683cc9126741d1.json"
  212.       }
  213.     ]
  214.   }
  215. }