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.twitter.com/1.1/geo/reverse_geocode.json
Response formats
|
JSON
|
Requires authentication?
|
Yes (user context only)
|
Rate limited?
|
Yes
|
Requests / 15-min window (user auth)
|
15
|
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.
|
|
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.twitter.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.twitter.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.twitter.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.twitter.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.twitter.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.twitter.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.twitter.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.twitter.com/1.1/geo/id/96683cc9126741d1.json"
}
]
}
}