This snapshot, taken on
27/09/2010
, shows web content acquired for preservation by The National Archives. External links, forms and search may not work in archived websites and contact details are likely to be out of date.
 
 
The UK Government Web Archive does not use cookies but some may be left in your browser from archived websites.

Basic Auth has been deprecated.

Attention! August 31, 2010 Basic Auth has been deprecated. All applications must now use OAuth. Read more »   x

Don't fret! @twitterapi is here to help! Feel free to reach out to us directly, or via our Twitter Development Talk group.

The switch to OAuth is a good thing! You, as the application developer,

  • don't have the burden of keeping potentially damaging credentials for your users (especially considering that a lot of people use the same password for multiple services);
  • don't have to worry about the user changing their password — a user can change his or her password and the OAuth "connection" to your app will still work;
  • don't have to worry about other applications masquerading as your application as only your application can set the byline with your application name;
  • will eventually have access to more trusted APIs from Twitter that will only be available to "trusted" OAuth-enabled applications; and
  • will be contributing to the web of trust between users, service providers, and applications.

Choose your authorization path.

GET geo/reverse_geocode

Home › Documentation › Geo Resources › 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.

URL

http://api.twitter.com/version/geo/reverse_geocode.format

Supported formats

json

Supported request methods

GET

Requires Authentication

false About authentication »

Rate Limited

true About rate limiting »

Parameters

Required

  • lat 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.
    • http://api.twitter.com/1/geo/reverse_geocode.json?lat=37.7821120598956
  • long 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.
    • http://api.twitter.com/1/geo/reverse_geocode.json?long=-122.400612831116

Optional

  • accuracy 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.).
    • http://api.twitter.com/1/geo/reverse_geocode.json?accuracy=5ft
  • granularity 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.
    • http://api.twitter.com/1/geo/reverse_geocode.json?granularity=city
  • max_results 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.
    • http://api.twitter.com/1/geo/reverse_geocode.json?max_results=3
  • callback If supplied, the response will use the JSONP format with a callback of the given name.

Example requests

JSON

Try it! » twurl /1/geo/reverse_geocode.json 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231

{
  "result": {
    "places": [
      {
        "name": "SoMa",
        "country": "The United States of America",
        "country_code": "US",
        "attributes": {

        },
        "url": "http://api.twitter.com/1/geo/id/2b6ff8c22edd9576.json",
        "id": "2b6ff8c22edd9576",
        "bounding_box": {
          "coordinates": [
            [
              [
                -122.42284884,
                37.76893497
              ],
              [
                -122.3964,
                37.76893497
              ],
              [
                -122.3964,
                37.78752897
              ],
              [
                -122.42284884,
                37.78752897
              ]
            ]
          ],
          "type": "Polygon"
        },
        "contained_within": [
          {
            "name": "San Francisco",
            "country": "The United States of America",
            "country_code": "US",
            "attributes": {

            },
            "url": "http://api.twitter.com/1/geo/id/5a110d312052166f.json",
            "id": "5a110d312052166f",
            "bounding_box": {
              "coordinates": [
                [
                  [
                    -122.51368188,
                    37.70813196
                  ],
                  [
                    -122.35845384,
                    37.70813196
                  ],
                  [
                    -122.35845384,
                    37.83245301
                  ],
                  [
                    -122.51368188,
                    37.83245301
                  ]
                ]
              ],
              "type": "Polygon"
            },
            "full_name": "San Francisco, CA",
            "place_type": "city"
          }
        ],
        "full_name": "SoMa, San Francisco",
        "place_type": "neighborhood"
      },
      {
        "name": "San Francisco",
        "country": "The United States of America",
        "country_code": "US",
        "attributes": {

        },
        "url": "http://api.twitter.com/1/geo/id/5a110d312052166f.json",
        "id": "5a110d312052166f",
        "bounding_box": {
          "coordinates": [
            [
              [
                -122.51368188,
                37.70813196
              ],
              [
                -122.35845384,
                37.70813196
              ],
              [
                -122.35845384,
                37.83245301
              ],
              [
                -122.51368188,
                37.83245301
              ]
            ]
          ],
          "type": "Polygon"
        },
        "contained_within": [
          {
            "name": "California",
            "country": "The United States of America",
            "country_code": "US",
            "attributes": {

            },
            "url": "http://api.twitter.com/1/geo/id/fbd6d2f5a4e4a15e.json",
            "id": "fbd6d2f5a4e4a15e",
            "bounding_box": {
              "coordinates": [
                [
                  [
                    -124.482003,
                    32.528832
                  ],
                  [
                    -114.131211,
                    32.528832
                  ],
                  [
                    -114.131211,
                    42.009517
                  ],
                  [
                    -124.482003,
                    42.009517
                  ]
                ]
              ],
              "type": "Polygon"
            },
            "full_name": "California, US",
            "place_type": "admin"
          }
        ],
        "full_name": "San Francisco, CA",
        "place_type": "city"
      },
      {
        "name": "California",
        "country": "The United States of America",
        "country_code": "US",
        "attributes": {

        },
        "url": "http://api.twitter.com/1/geo/id/fbd6d2f5a4e4a15e.json",
        "id": "fbd6d2f5a4e4a15e",
        "bounding_box": {
          "coordinates": [
            [
              [
                -124.482003,
                32.528832
              ],
              [
                -114.131211,
                32.528832
              ],
              [
                -114.131211,
                42.009517
              ],
              [
                -124.482003,
                42.009517
              ]
            ]
          ],
          "type": "Polygon"
        },
        "contained_within": [
          {
            "name": "The United States of America",
            "country": "The United States of America",
            "country_code": "US",
            "attributes": {

            },
            "url": "http://api.twitter.com/1/geo/id/96683cc9126741d1.json",
            "id": "96683cc9126741d1",
            "bounding_box": null,
            "full_name": "The United States of America",
            "place_type": "country"
          }
        ],
        "full_name": "California, US",
        "place_type": "admin"
      },
      {
        "name": "The United States of America",
        "country": "The United States of America",
        "country_code": "US",
        "attributes": {

        },
        "url": "http://api.twitter.com/1/geo/id/96683cc9126741d1.json",
        "id": "96683cc9126741d1",
        "bounding_box": null,
        "contained_within": [

        ],
        "full_name": "The United States of America",
        "place_type": "country"
      }
    ]
  },
  "query": {
    "url": "http://api.twitter.com/1/geo/reverse_geocode.json?lat=37.781157&accuracy=0&long=-122.398720&granularity=neighborhood",
    "type": "reverse_geocode",
    "params": {
      "coordinates": {
        "coordinates": [
          -122.39872,
          37.781157
        ],
        "type": "Point"
      },
      "granularity": "neighborhood",
      "accuracy": 0
    }
  }
}

Related Documentation

This document last updated by themattharris on June 22, 2010