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
coordinatesobject 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-revers...
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%A0...)
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
