Developer Preview: upcoming geo features (a.k.a "A place is not just a latitude and a longitude - it has a name")

1,836 views

Skip to first unread message

Raffi Krikorian

unread,

Mar 1, 2010, 8:44:19 PM3/1/10

to twitter-ap...@googlegroups.com, twitter-deve...@googlegroups.com

hi all.

i wanted to give you all a heads up on some big changes we're making to our geo-tagging API. right now, you can post a status update along with a latitude and longitude pair -- what we've jokingly referred to as "geo-tweeting", is actually just a status update with a "where" in the form of a coordinate attached to it. we're about to add a whole new layer of context to that status update.

our goal is to provide a few more options to API developers (and the users they are servicing) through this contextual information. people, we find, inherently want to talk about a "place". a place, for a lot of people, has a name and is not a latitude and longitude pair. (37.78215, -122.40060), for example, doesn't mean a lot to a lot of people -- but, "San Francisco, CA, USA" does. we're also trying to help users who aren't comfortable annotating their tweets with their exact coordinates, but, instead, are really happy to say what city, or even neighborhood, they are in. annotating your place with a name does that too.

once our new additions to our geo infrastructure comes into place, geo-tweets will get richer data. for example, a status object may look like the following (abbreviated):

{

"id":9505317221,

...

"coordinates": {

"type":"Point",

"coordinates": [-122.40060, 37.78215]

"place": {

"country":"United States",

"country_code":"US",

"full_name":"SoMa, San Francisco",

"name":"SoMa",

"place_type":"neighborhood",

"bounding_box": {

"type":"Polygon",

"coordinates": [

[

[ -122.42284884, 37.76893497 ],

[ -122.3964, 37.76893497 ],

[ -122.3964, 37.78752897 ],

[ -122.42284884, 37.78752897 ]

]

"id":"7695dd2ec2f86f2b",

"url":"/1/geo/id/7695dd2ec2f86f2b.json"

...

"text":"Wherever you go, there you are."

}

here you'll see a new place attribute that gives the contextual location of the geo-tweet itself. in these cases, you'll have rich, and human-readable, information about where this tweet has come from -- in this case, SoMa, San Francisco. the geo object, for the time being, is still there, so you don't have to worry about backwards compatibility. it will soon be deprecated, however and please plan for that. we're also introducing a coordinates object which has the added bonus that, when in JSON, it is properly GeoJSON encoded with the longitude before latitude.

to support this these changes we've added a few endpoints:

https://apiwiki.twitter.com/Twitter-REST-API-Method%3A-GET-geo-reverse_geocode

https://apiwiki.twitter.com/Twitter-REST-API-Method%3A-GET-geo-ID

you can call geo/reverse_geocode with a latitude and longitude, and it will return an array of places that you can use to annotate your tweet with. each place that is returned will have a unique ID that you can use, as well as a displayable name, and even a geographical bounding box that you can use for display on a map. if you want more details, then hit the geo/id endpoint where, if available, and if you're interested, you can retrieve a more detailed geometry for more accurate map drawing. we've also updated the statuses/update documentation (https://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses%C2%A0update) to indicate how to pass that place ID with your status update.

for this first pass, we're only going live with United States-centric data, but that will quickly be expanded geographically as we work out the kinks in our system. there are definitely some nuances that i'm missing in this e-mail, a few things are still in flux, but we're rapidly documenting this on our wiki, and we hope to be going live with it quite soon. as always, if you have any questions, just find us at @twitterapi, or drop us an e-mail.