GET geo/reverse_geocode

Updated on Wed, 2012-04-18 11:23

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

http://api.twitter.com/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/geo/reverse_geocode.json?lat=37.76893497&long=-122.42284884

  1. {
  2.   "result": {
  3.     "places": [
  4.       {
  5.         "name": "SoMa",
  6.         "country": "The United States of America",
  7.         "country_code": "US",
  8.         "attributes": {
  9.  
  10.         },
  11.         "url": "http://api.twitter.com/1/geo/id/2b6ff8c22edd9576.json",
  12.         "id": "2b6ff8c22edd9576",
  13.         "bounding_box": {
  14.           "coordinates": [
  15.             [
  16.               [
  17.                 -122.42284884,
  18.                 37.76893497
  19.               ],
  20.               [
  21.                 -122.3964,
  22.                 37.76893497
  23.               ],
  24.               [
  25.                 -122.3964,
  26.                 37.78752897
  27.               ],
  28.               [
  29.                 -122.42284884,
  30.                 37.78752897
  31.               ]
  32.             ]
  33.           ],
  34.           "type": "Polygon"
  35.         },
  36.         "contained_within": [
  37.           {
  38.             "name": "San Francisco",
  39.             "country": "The United States of America",
  40.             "country_code": "US",
  41.             "attributes": {
  42.  
  43.             },
  44.             "url": "http://api.twitter.com/1/geo/id/5a110d312052166f.json",
  45.             "id": "5a110d312052166f",
  46.             "bounding_box": {
  47.               "coordinates": [
  48.                 [
  49.                   [
  50.                     -122.51368188,
  51.                     37.70813196
  52.                   ],
  53.                   [
  54.                     -122.35845384,
  55.                     37.70813196
  56.                   ],
  57.                   [
  58.                     -122.35845384,
  59.                     37.83245301
  60.                   ],
  61.                   [
  62.                     -122.51368188,
  63.                     37.83245301
  64.                   ]
  65.                 ]
  66.               ],
  67.               "type": "Polygon"
  68.             },
  69.             "full_name": "San Francisco, CA",
  70.             "place_type": "city"
  71.           }
  72.         ],
  73.         "full_name": "SoMa, San Francisco",
  74.         "place_type": "neighborhood"
  75.       },
  76.       {
  77.         "name": "San Francisco",
  78.         "country": "The United States of America",
  79.         "country_code": "US",
  80.         "attributes": {
  81.  
  82.         },
  83.         "url": "http://api.twitter.com/1/geo/id/5a110d312052166f.json",
  84.         "id": "5a110d312052166f",
  85.         "bounding_box": {
  86.           "coordinates": [
  87.             [
  88.               [
  89.                 -122.51368188,
  90.                 37.70813196
  91.               ],
  92.               [
  93.                 -122.35845384,
  94.                 37.70813196
  95.               ],
  96.               [
  97.                 -122.35845384,
  98.                 37.83245301
  99.               ],
  100.               [
  101.                 -122.51368188,
  102.                 37.83245301
  103.               ]
  104.             ]
  105.           ],
  106.           "type": "Polygon"
  107.         },
  108.         "contained_within": [
  109.           {
  110.             "name": "California",
  111.             "country": "The United States of America",
  112.             "country_code": "US",
  113.             "attributes": {
  114.  
  115.             },
  116.             "url": "http://api.twitter.com/1/geo/id/fbd6d2f5a4e4a15e.json",
  117.             "id": "fbd6d2f5a4e4a15e",
  118.             "bounding_box": {
  119.               "coordinates": [
  120.                 [
  121.                   [
  122.                     -124.482003,
  123.                     32.528832
  124.                   ],
  125.                   [
  126.                     -114.131211,
  127.                     32.528832
  128.                   ],
  129.                   [
  130.                     -114.131211,
  131.                     42.009517
  132.                   ],
  133.                   [
  134.                     -124.482003,
  135.                     42.009517
  136.                   ]
  137.                 ]
  138.               ],
  139.               "type": "Polygon"
  140.             },
  141.             "full_name": "California, US",
  142.             "place_type": "admin"
  143.           }
  144.         ],
  145.         "full_name": "San Francisco, CA",
  146.         "place_type": "city"
  147.       },
  148.       {
  149.         "name": "California",
  150.         "country": "The United States of America",
  151.         "country_code": "US",
  152.         "attributes": {
  153.  
  154.         },
  155.         "url": "http://api.twitter.com/1/geo/id/fbd6d2f5a4e4a15e.json",
  156.         "id": "fbd6d2f5a4e4a15e",
  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.             "name": "The United States of America",
  183.             "country": "The United States of America",
  184.             "country_code": "US",
  185.             "attributes": {
  186.  
  187.             },
  188.             "url": "http://api.twitter.com/1/geo/id/96683cc9126741d1.json",
  189.             "id": "96683cc9126741d1",
  190.             "bounding_box": null,
  191.             "full_name": "The United States of America",
  192.             "place_type": "country"
  193.           }
  194.         ],
  195.         "full_name": "California, US",
  196.         "place_type": "admin"
  197.       },
  198.       {
  199.         "name": "The United States of America",
  200.         "country": "The United States of America",
  201.         "country_code": "US",
  202.         "attributes": {
  203.  
  204.         },
  205.         "url": "http://api.twitter.com/1/geo/id/96683cc9126741d1.json",
  206.         "id": "96683cc9126741d1",
  207.         "bounding_box": null,
  208.         "contained_within": [
  209.  
  210.         ],
  211.         "full_name": "The United States of America",
  212.         "place_type": "country"
  213.       }
  214.     ]
  215.   },
  216.   "query": {
  217.     "url": "http://api.twitter.com/1/geo/reverse_geocode.json?lat=37.781157&accuracy=0&long=-122.398720&granularity=neighborhood",
  218.     "type": "reverse_geocode",
  219.     "params": {
  220.       "coordinates": {
  221.         "coordinates": [
  222.           -122.39872,
  223.           37.781157
  224.         ],
  225.         "type": "Point"
  226.       },
  227.       "granularity": "neighborhood",
  228.       "accuracy": 0
  229.     }
  230.   }
  231. }