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

[Raffi Krikorian]

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.

--
Raffi Krikorian
Twitter Platform Team
http://twitter.com/raffi

[M. Edward (Ed) Borasky]

Awesome! That is a big step forward! How soon do you think this will
be rolled out to a couple of obvious places - Haiti and Chile? I've
got a lot of friends in the disaster response and the mapping
communities that are working hard to map places via mobiles, and there
are as a result huge and free as in freedom databases you can access.
--
M. Edward (Ed) Borasky
borasky-research.net/m-edward-ed-borasky/

"A mathematician is a device for turning coffee into theorems." ~ Paul Erdos

Quoting Raffi Krikorian <ra...@twitter.com>:

> 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-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

[Dominik Schwind]

This is awesome!
And please tell me you'll be using the WoeIDs for that.

Dominik

> 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...)

[Rich]

Excellent news, just updating my backend to use the coordinates/place
tags in addition to geo.

I'd be interested to know when display_coordinates parameter of
statuses/update is planned to go live so I can add adding places to
instead of coordinates as an option to my users.

[Rich]

Something that's not all that obvious, in statuses/update

The parameters of place_id and display_coordinates. Are they linked,
i.e. if i specify display_coordinates as false do I have to specify a
place_id or will your backend automatically convert any coordinates to
a place?

[Raffi Krikorian]

unclear, but we'll definitely message out to the list as we make more of our datasets available.

On Mon, Mar 1, 2010 at 10:15 PM, M. Edward (Ed) Borasky <zn...@cesmail.net> wrote:

Awesome! That is a big step forward! How soon do you think this will be rolled out to a couple of obvious places - Haiti and Chile? I've got a lot of friends in the disaster response and the mapping communities that are working hard to map places via mobiles, and there are as a result huge and free as in freedom databases you can access.
--
M. Edward (Ed) Borasky
borasky-research.net/m-edward-ed-borasky/

"A mathematician is a device for turning coffee into theorems." ~ Paul Erd?s

Quoting Raffi Krikorian <ra...@twitter.com>:

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-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]

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!

[Raffi Krikorian]

at day one, there won't be a WOEID ID match on this endpoint -- it is on our list, however, and we will get to it.

[Ed Costello]

Calls to http://api.twitter.com/1/geo/id/7695dd2ec2f86f2b.xml return JSON, while appending any other extension (.html, .raffi, etc) return a 1 byte 403 error (0x20).  Since XML isn't supported according to the wiki docs, maybe return 403 for .xml as well?

--
-ed costello
@epc / +13474080372

[Raffi Krikorian]

yup - thanks for catching that.  only JSON is supported, and we'll track down why the others are returning anything.

[M. Edward (Ed) Borasky]

I can put out a call on the "CrisisMapper" and other lists I'm on if
Twitter needs help getting such databases - I just got into this game
in mid-January and don't know what all is available.

[bob.hitching]

good stuff raffi, any further news on if/when the new <place> data
will be exposed via the Search API?

cheers, bob

GeoMeme - http://www.geome.me - what's happening where?

> 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...)

[Raffi Krikorian]

hi bob.

"soon" :P

To unsubscribe from this group, send email to twitter-development-talk+unsubscribegooglegroups.com or reply to this email with the words "REMOVE ME" as the subject.

[Peter Kieltyka]

Raffi,

I find the biggest hurdle with geo-tweets right now is that very few
twitter users actually have it enabled. And I believe for a very good
reason as sending the exact coordinate of a tweet has serious privacy
issues. For example, a girl takes a picture of her new hairdo from her
bedroom and tweets it, but forgot she had geo-tagging set, some freak
on the net decides to pay her a visit, scary stuff.

As that example suggests, these cases have to be handled with absolute
care, but the downside of putting up so many barriers to enable geo-
tweeting is it creates resistance for adoption. I feel that unless
Twitter allows services to enable geo-tweeting on a neighbourhood
scale via the API, then adoption will continually be low.
Neighbourhood (or city) tagging isn't invasive, not anymore then what
many users put in under their "location" bio.

Are there any plans for a spectrum of security for geo-tagging on a
coordinate / neighbourhood / city scale?

Thanks.

Peter

On Mar 26, 5:11 pm, Raffi Krikorian <ra...@twitter.com> wrote:
> hi bob.
>
> "soon" :P
>
>
>
>
>
> On Fri, Mar 26, 2010 at 2:06 PM, bob.hitching <b...@hitching.net> wrote:
> > good stuff raffi, any further news on if/when the new <place> data
> > will be exposed via the Search API?
>
> > cheers, bob
>

> > GeoMeme -http://www.geome.me- what's happening where?