GET geo/search

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

Search for places that can be attached to a statuses/update. Given a latitude and a longitude pair, an IP address, or a name, this request will return a list of all the valid places that can be used as the place_id when updating a status.

Conceptually, a query can be made from the user's location, retrieve a list of places, have the user validate the location he or she is at, and then send the ID of this location with a call to statuses/update.

This is the recommended method to use find places that can be attached to statuses/update. Unlike geo/reverse_geocode which provides raw data access, this endpoint can potentially re-order places with regards to the user who is authenticated. This approach is also preferred for interactive place matching with the user.

Resource URL

http://api.twitter.com/1/geo/search.json

Parameters

Note: At least one of the following parameters must be provided to this resource: lat, long, ip, or query

lat optional

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 optional

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

query optional

Free-form text to match against while executing a geo-based query, best suited for finding nearby locations by name. Remember to URL encode the query.

Example Values: Twitter%20HQ

ip optional

An IP address. Used when attempting to fix geolocation based off of the user's IP address.

Example Values: 74.125.19.104

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

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

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

attribute:street_address optional

This parameter searches for places which have this given street address. There are other well-known, and application specific attributes available. Custom attributes are also permitted. Learn more about Place Attributes.

Example Values: 795%20Folsom%20St

callback optional

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

Extended description

Some parameters in this method are only required based on the existence of other parameters. For instance, "lat" is required if "long" is provided, and vice-versa. Authentication is recommended, but not required with this method.

Example Request

GET

https://api.twitter.com/1/geo/search.json?query=Toronto

  1. {
  2.   "result": {
  3.     "places": [
  4.       {
  5.         "name": "Toronto",
  6.         "country_code": "US",
  7.         "country": "United States",
  8.         "attributes": {
  9.         },
  10.         "url": "http://api.twitter.com/1/geo/id/3e8542a1e9f82870.json",
  11.         "bounding_box": {
  12.           "coordinates": [
  13.             [
  14.               [
  15.                 -96.647415,
  16.                 44.566715
  17.               ],
  18.               [
  19.                 -96.630435,
  20.                 44.566715
  21.               ],
  22.               [
  23.                 -96.630435,
  24.                 44.578118
  25.               ],
  26.               [
  27.                 -96.647415,
  28.                 44.578118
  29.               ]
  30.             ]
  31.           ],
  32.           "type": "Polygon"
  33.         },
  34.         "id": "3e8542a1e9f82870",
  35.         "contained_within": [
  36.           {
  37.             "name": "South Dakota",
  38.             "country_code": "US",
  39.             "country": "United States",
  40.             "attributes": {
  41.             },
  42.             "url": "http://api.twitter.com/1/geo/id/d06e595eb3733f42.json",
  43.             "id": "d06e595eb3733f42",
  44.             "bounding_box": {
  45.               "coordinates": [
  46.                 [
  47.                   [
  48.                     -104.057739,
  49.                     42.479686
  50.                   ],
  51.                   [
  52.                     -96.436472,
  53.                     42.479686
  54.                   ],
  55.                   [
  56.                     -96.436472,
  57.                     45.945716
  58.                   ],
  59.                   [
  60.                     -104.057739,
  61.                     45.945716
  62.                   ]
  63.                 ]
  64.               ],
  65.               "type": "Polygon"
  66.             },
  67.             "full_name": "South Dakota, US",
  68.             "place_type": "admin"
  69.           }
  70.         ],
  71.         "full_name": "Toronto, SD",
  72.         "place_type": "city"
  73.       },
  74.       {
  75.         "name": "Toronto",
  76.         "country_code": "US",
  77.         "country": "United States",
  78.         "attributes": {
  79.         },
  80.         "url": "http://api.twitter.com/1/geo/id/53d949149e8cd438.json",
  81.         "bounding_box": {
  82.           "coordinates": [
  83.             [
  84.               [
  85.                 -80.622815,
  86.                 40.436469
  87.               ],
  88.               [
  89.                 -80.596567,
  90.                 40.436469
  91.               ],
  92.               [
  93.                 -80.596567,
  94.                 40.482566
  95.               ],
  96.               [
  97.                 -80.622815,
  98.                 40.482566
  99.               ]
  100.             ]
  101.           ],
  102.           "type": "Polygon"
  103.         },
  104.         "id": "53d949149e8cd438",
  105.         "contained_within": [
  106.           {
  107.             "name": "Ohio",
  108.             "country_code": "US",
  109.             "country": "United States",
  110.             "attributes": {
  111.             },
  112.             "url": "http://api.twitter.com/1/geo/id/de599025180e2ee7.json",
  113.             "id": "de599025180e2ee7",
  114.             "bounding_box": {
  115.               "coordinates": [
  116.                 [
  117.                   [
  118.                     -84.820305,
  119.                     38.403423
  120.                   ],
  121.                   [
  122.                     -80.518454,
  123.                     38.403423
  124.                   ],
  125.                   [
  126.                     -80.518454,
  127.                     42.327132
  128.                   ],
  129.                   [
  130.                     -84.820305,
  131.                     42.327132
  132.                   ]
  133.                 ]
  134.               ],
  135.               "type": "Polygon"
  136.             },
  137.             "full_name": "Ohio, US",
  138.             "place_type": "admin"
  139.           }
  140.         ],
  141.         "full_name": "Toronto, OH",
  142.         "place_type": "city"
  143.       },
  144.       {
  145.         "name": "Toronto",
  146.         "country_code": "CA",
  147.         "country": "Canada",
  148.         "attributes": {
  149.         },
  150.         "url": "http://api.twitter.com/1/geo/id/8f9664a8ccd89e5c.json",
  151.         "bounding_box": {
  152.           "coordinates": [
  153.             [
  154.               [
  155.                 -79.639128,
  156.                 43.403221
  157.               ],
  158.               [
  159.                 -78.90582,
  160.                 43.403221
  161.               ],
  162.               [
  163.                 -78.90582,
  164.                 43.855466
  165.               ],
  166.               [
  167.                 -79.639128,
  168.                 43.855466
  169.               ]
  170.             ]
  171.           ],
  172.           "type": "Polygon"
  173.         },
  174.         "id": "8f9664a8ccd89e5c",
  175.         "contained_within": [
  176.           {
  177.             "name": "Ontario",
  178.             "country_code": "CA",
  179.             "country": "Canada",
  180.             "attributes": {
  181.             },
  182.             "url": "http://api.twitter.com/1/geo/id/89b2eb8b2b9847f7.json",
  183.             "id": "89b2eb8b2b9847f7",
  184.             "bounding_box": {
  185.               "coordinates": [
  186.                 [
  187.                   [
  188.                     -95.155919,
  189.                     41.676329
  190.                   ],
  191.                   [
  192.                     -74.339383,
  193.                     41.676329
  194.                   ],
  195.                   [
  196.                     -74.339383,
  197.                     56.852398
  198.                   ],
  199.                   [
  200.                     -95.155919,
  201.                     56.852398
  202.                   ]
  203.                 ]
  204.               ],
  205.               "type": "Polygon"
  206.             },
  207.             "full_name": "Ontario, Canada",
  208.             "place_type": "admin"
  209.           }
  210.         ],
  211.         "full_name": "Toronto, Ontario",
  212.         "place_type": "city"
  213.       },
  214.       {
  215.         "name": "Toronto",
  216.         "country_code": "US",
  217.         "country": "United States",
  218.         "attributes": {
  219.         },
  220.         "url": "http://api.twitter.com/1/geo/id/173d6f9c3249b4fd.json",
  221.         "bounding_box": {
  222.           "coordinates": [
  223.             [
  224.               [
  225.                 -90.867234,
  226.                 41.898723
  227.               ],
  228.               [
  229.                 -90.859467,
  230.                 41.898723
  231.               ],
  232.               [
  233.                 -90.859467,
  234.                 41.906811
  235.               ],
  236.               [
  237.                 -90.867234,
  238.                 41.906811
  239.               ]
  240.             ]
  241.           ],
  242.           "type": "Polygon"
  243.         },
  244.         "id": "173d6f9c3249b4fd",
  245.         "contained_within": [
  246.           {
  247.             "name": "Iowa",
  248.             "country_code": "US",
  249.             "country": "United States",
  250.             "attributes": {
  251.             },
  252.             "url": "http://api.twitter.com/1/geo/id/3cd4c18d3615bbc9.json",
  253.             "id": "3cd4c18d3615bbc9",
  254.             "bounding_box": {
  255.               "coordinates": [
  256.                 [
  257.                   [
  258.                     -96.639485,
  259.                     40.375437
  260.                   ],
  261.                   [
  262.                     -90.140061,
  263.                     40.375437
  264.                   ],
  265.                   [
  266.                     -90.140061,
  267.                     43.501196
  268.                   ],
  269.                   [
  270.                     -96.639485,
  271.                     43.501196
  272.                   ]
  273.                 ]
  274.               ],
  275.               "type": "Polygon"
  276.             },
  277.             "full_name": "Iowa, US",
  278.             "place_type": "admin"
  279.           }
  280.         ],
  281.         "full_name": "Toronto, IA",
  282.         "place_type": "city"
  283.       },
  284.       {
  285.         "name": "Toronto",
  286.         "country_code": "US",
  287.         "country": "United States",
  288.         "attributes": {
  289.         },
  290.         "url": "http://api.twitter.com/1/geo/id/b90e4628bff4ad82.json",
  291.         "bounding_box": {
  292.           "coordinates": [
  293.             [
  294.               [
  295.                 -95.956873,
  296.                 37.792724
  297.               ],
  298.               [
  299.                 -95.941288,
  300.                 37.792724
  301.               ],
  302.               [
  303.                 -95.941288,
  304.                 37.803752
  305.               ],
  306.               [
  307.                 -95.956873,
  308.                 37.803752
  309.               ]
  310.             ]
  311.           ],
  312.           "type": "Polygon"
  313.         },
  314.         "id": "b90e4628bff4ad82",
  315.         "contained_within": [
  316.           {
  317.             "name": "Kansas",
  318.             "country_code": "US",
  319.             "country": "United States",
  320.             "attributes": {
  321.             },
  322.             "url": "http://api.twitter.com/1/geo/id/27c45d804c777999.json",
  323.             "bounding_box": {
  324.               "coordinates": [
  325.                 [
  326.                   [
  327.                     -102.051769,
  328.                     36.993016
  329.                   ],
  330.                   [
  331.                     -94.588387,
  332.                     36.993016
  333.                   ],
  334.                   [
  335.                     -94.588387,
  336.                     40.003166
  337.                   ],
  338.                   [
  339.                     -102.051769,
  340.                     40.003166
  341.                   ]
  342.                 ]
  343.               ],
  344.               "type": "Polygon"
  345.             },
  346.             "id": "27c45d804c777999",
  347.             "full_name": "Kansas, US",
  348.             "place_type": "admin"
  349.           }
  350.         ],
  351.         "full_name": "Toronto, KS",
  352.         "place_type": "city"
  353.       }
  354.     ]
  355.   },
  356.   "query": {
  357.     "url": "http://api.twitter.com/1/geo/search.json?query=Toronto&autocomplete=false&granularity=neighborhood&accuracy=0&trim_place=false",
  358.     "type": "search",
  359.     "params": {
  360.       "accuracy": 0,
  361.       "granularity": "neighborhood",
  362.       "trim_place": false,
  363.       "query": "Toronto",
  364.       "autocomplete": false
  365.     }
  366.   }
  367. }