Get places near a location

API Reference contents

GET geo/search

Search for places that can be attached to a Tweet via POST 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 they are at, and then send the ID of this location with a call to POST statuses/update.

This is the recommended method to use find places that can be attached to statuses/update. Unlike GET 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.

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.

Resource URL

https://api.twitter.com/1.1/geo/search.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 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. 37.7821120598956
long optional 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 disabled, or if there not a corresponding lat parameter. -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. Twitter%20HQ
ip optional An IP address. Used when attempting to fix geolocation based off of the user's IP address. 74.125.19.104
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
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
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
contained_within optional

This is the place_id which you would like to restrict the search results to. Setting this value means only places within the given place_id will be found.

Specify a place_id. For example, to scope all results to places within "San Francisco, CA USA", you would specify a place_id of "5a110d312052166f".

247f43d441defc03
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. 795%20Folsom%20St

Example Request

twurl /1.1/geo/search.json?query=Toronto

Example Response

{
  "query": {
    "params": {
      "accuracy": 0,
      "autocomplete": false,
      "granularity": "neighborhood",
      "query": "Toronto",
      "trim_place": false
    },
    "type": "search",
    "url": "https://api.twitter.com/1.1/geo/search.json?accuracy=0&query=Toronto&granularity=neighborhood&autocomplete=false&trim_place=false"
  },
  "result": {
    "places": [
      {
        "attributes": {},
        "bounding_box": {
          "coordinates": [
            [
              [
                -96.647415,
                44.566715
              ],
              [
                -96.630435,
                44.566715
              ],
              [
                -96.630435,
                44.578118
              ],
              [
                -96.647415,
                44.578118
              ]
            ]
          ],
          "type": "Polygon"
        },
        "contained_within": [
          {
            "attributes": {},
            "bounding_box": {
              "coordinates": [
                [
                  [
                    -104.057739,
                    42.479686
                  ],
                  [
                    -96.436472,
                    42.479686
                  ],
                  [
                    -96.436472,
                    45.945716
                  ],
                  [
                    -104.057739,
                    45.945716
                  ]
                ]
              ],
              "type": "Polygon"
            },
            "country": "United States",
            "country_code": "US",
            "full_name": "South Dakota, US",
            "id": "d06e595eb3733f42",
            "name": "South Dakota",
            "place_type": "admin",
            "url": "https://api.twitter.com/1.1/geo/id/d06e595eb3733f42.json"
          }
        ],
        "country": "United States",
        "country_code": "US",
        "full_name": "Toronto, SD",
        "id": "3e8542a1e9f82870",
        "name": "Toronto",
        "place_type": "city",
        "url": "https://api.twitter.com/1.1/geo/id/3e8542a1e9f82870.json"
      },
      {
        "attributes": {},
        "bounding_box": {
          "coordinates": [
            [
              [
                -80.622815,
                40.436469
              ],
              [
                -80.596567,
                40.436469
              ],
              [
                -80.596567,
                40.482566
              ],
              [
                -80.622815,
                40.482566
              ]
            ]
          ],
          "type": "Polygon"
        },
        "contained_within": [
          {
            "attributes": {},
            "bounding_box": {
              "coordinates": [
                [
                  [
                    -84.820305,
                    38.403423
                  ],
                  [
                    -80.518454,
                    38.403423
                  ],
                  [
                    -80.518454,
                    42.327132
                  ],
                  [
                    -84.820305,
                    42.327132
                  ]
                ]
              ],
              "type": "Polygon"
            },
            "country": "United States",
            "country_code": "US",
            "full_name": "Ohio, US",
            "id": "de599025180e2ee7",
            "name": "Ohio",
            "place_type": "admin",
            "url": "https://api.twitter.com/1.1/geo/id/de599025180e2ee7.json"
          }
        ],
        "country": "United States",
        "country_code": "US",
        "full_name": "Toronto, OH",
        "id": "53d949149e8cd438",
        "name": "Toronto",
        "place_type": "city",
        "url": "https://api.twitter.com/1.1/geo/id/53d949149e8cd438.json"
      },
      {
        "attributes": {},
        "bounding_box": {
          "coordinates": [
            [
              [
                -79.639128,
                43.403221
              ],
              [
                -78.90582,
                43.403221
              ],
              [
                -78.90582,
                43.855466
              ],
              [
                -79.639128,
                43.855466
              ]
            ]
          ],
          "type": "Polygon"
        },
        "contained_within": [
          {
            "attributes": {},
            "bounding_box": {
              "coordinates": [
                [
                  [
                    -95.155919,
                    41.676329
                  ],
                  [
                    -74.339383,
                    41.676329
                  ],
                  [
                    -74.339383,
                    56.852398
                  ],
                  [
                    -95.155919,
                    56.852398
                  ]
                ]
              ],
              "type": "Polygon"
            },
            "country": "Canada",
            "country_code": "CA",
            "full_name": "Ontario, Canada",
            "id": "89b2eb8b2b9847f7",
            "name": "Ontario",
            "place_type": "admin",
            "url": "https://api.twitter.com/1.1/geo/id/89b2eb8b2b9847f7.json"
          }
        ],
        "country": "Canada",
        "country_code": "CA",
        "full_name": "Toronto, Ontario",
        "id": "8f9664a8ccd89e5c",
        "name": "Toronto",
        "place_type": "city",
        "url": "https://api.twitter.com/1.1/geo/id/8f9664a8ccd89e5c.json"
      },
      {
        "attributes": {},
        "bounding_box": {
          "coordinates": [
            [
              [
                -90.867234,
                41.898723
              ],
              [
                -90.859467,
                41.898723
              ],
              [
                -90.859467,
                41.906811
              ],
              [
                -90.867234,
                41.906811
              ]
            ]
          ],
          "type": "Polygon"
        },
        "contained_within": [
          {
            "attributes": {},
            "bounding_box": {
              "coordinates": [
                [
                  [
                    -96.639485,
                    40.375437
                  ],
                  [
                    -90.140061,
                    40.375437
                  ],
                  [
                    -90.140061,
                    43.501196
                  ],
                  [
                    -96.639485,
                    43.501196
                  ]
                ]
              ],
              "type": "Polygon"
            },
            "country": "United States",
            "country_code": "US",
            "full_name": "Iowa, US",
            "id": "3cd4c18d3615bbc9",
            "name": "Iowa",
            "place_type": "admin",
            "url": "https://api.twitter.com/1.1/geo/id/3cd4c18d3615bbc9.json"
          }
        ],
        "country": "United States",
        "country_code": "US",
        "full_name": "Toronto, IA",
        "id": "173d6f9c3249b4fd",
        "name": "Toronto",
        "place_type": "city",
        "url": "https://api.twitter.com/1.1/geo/id/173d6f9c3249b4fd.json"
      },
      {
        "attributes": {},
        "bounding_box": {
          "coordinates": [
            [
              [
                -95.956873,
                37.792724
              ],
              [
                -95.941288,
                37.792724
              ],
              [
                -95.941288,
                37.803752
              ],
              [
                -95.956873,
                37.803752
              ]
            ]
          ],
          "type": "Polygon"
        },
        "contained_within": [
          {
            "attributes": {},
            "bounding_box": {
              "coordinates": [
                [
                  [
                    -102.051769,
                    36.993016
                  ],
                  [
                    -94.588387,
                    36.993016
                  ],
                  [
                    -94.588387,
                    40.003166
                  ],
                  [
                    -102.051769,
                    40.003166
                  ]
                ]
              ],
              "type": "Polygon"
            },
            "country": "United States",
            "country_code": "US",
            "full_name": "Kansas, US",
            "id": "27c45d804c777999",
            "name": "Kansas",
            "place_type": "admin",
            "url": "https://api.twitter.com/1.1/geo/id/27c45d804c777999.json"
          }
        ],
        "country": "United States",
        "country_code": "US",
        "full_name": "Toronto, KS",
        "id": "b90e4628bff4ad82",
        "name": "Toronto",
        "place_type": "city",
        "url": "https://api.twitter.com/1.1/geo/id/b90e4628bff4ad82.json"
      }
    ]
  }
}