as a follow up to this, if you want to see a fully formed example in the wild, then just grab http://twitter.com/statuses/show/9882866425.xml.
have fun! On Mon, Mar 1, 2010 at 5:44 PM, Raffi Krikorian <[email protected]> wrote: > 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/idendpoint > 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. > > -- > Raffi Krikorian > Twitter Platform Team > http://twitter.com/raffi > -- Raffi Krikorian Twitter Platform Team http://twitter.com/raffi
