Developer Preview: Geolocation API

[Ryan Sarver]

We wanted to give you all a heads up on a cool new feature that is coming soon - Geolocation. The Geolocation API will give us the ability to attach geographic metadata to tweets to provide additional context with your update. Along with the option to tag updates, we will be able to search for nearby tweets and view the geo metadata in user timelines. The additional context allows for us to deliver more meaningful and localized experiences to users. We are also really excited about a unique facet of this release in that it will be API-only initially. This means that Twitter.com won't surface the functionality and we look forward to seeing the new and interesting experiences that will grow out of the ecosystem.

As part of our Geolocation efforts we will soon be publishing "Geolocation Best Pracitices" to guide everyone through issues like security and privacy as well as discussing some ideal experiences for users. Topics will include things like storage of location data, what to do with a user's historical data, how to present the concept of geotagging and more. The guide will create a framework from which we can address the challenges that come about when dealing with something as sensitive as someone's location while hopefully allowing everyone enough creative freedom to create their own experiences around it.

It is important to note that the feature is going to be strictly opt-in. It will be disabled until a user chooses to switch it on. We will provide a read-only attribute <geo_enabled> on the user object so an app can detect if the user has it disabled and let them know if they need to turn it on before using a geolocation feature.

While we can't provide an exact date for launch, you should plan on having a few weeks of development time before the new API is officially launched. With that being said, lets get to it...

Example: Geotagging a Tweet
-----------------------
curl -d "lat=37.780467&long=-122.396762&status=I have arrived" -u user:pass "http://twitter.com/statuses/update.xml"

<?xml version="1.0" encoding="UTF-8"?>

<status>

<created_at>Tue Apr 07 22:52:51 +0000 2009</created_at>

...

<geo xmlns:georss="http://www.georss.org/georss">

<georss:point>37.780467 -122.396762</georss:point>

</geo>

<user>

<id>1401881</id>

<name>Doug Williams</name>

...

<geo_enabled>true</geo_enabled>

...

</user>

</status>

We have also updated the wiki to reflect what the API will look like when it launches, so check it out and let us know if you have any questions:
http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses%C2%A0update

http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-account%C2%A0verify_credentials

We'll also be in our recently announced IRC channel (#twitterapi on irc.freenode.net) if you want to discuss the announcement with the team.

Ryan

PM, Platform Team

http://twitter.com/rsarver

[@epc]

Will twitter validate the coordinates (ie, what will the API do when I
pass lat=777&long=-666)?

If the coordinates are invalid, will the status get posted or will the
entire request get rejected with a 4xx code?

If a user has not enabled geolocating (<geo_enabled>false</
geo_enabled>), what happens if I pass in coordinates for that user?
Silently ignored?

Geo data will be attached to individual tweets and not users, right?
This will have no effect on the <location> field in a user profile?
--
-ed costello

[Joel Strellner]

Hi Ryan,

Will this data be available in the streaming API too?

-Joel

[@epc]

Will the opt–in method be only through the twitter site or will there
be an API method to turn it on/off?
--

[jim.renkel]

Um, I don't see any way for a user to turn the <geo_enabled> attribute
on and off. Oversight, I hope?

Jim

On Aug 20, 4:18 pm, Joel Strellner <j...@twitturly.com> wrote:
> Hi Ryan,
>
> Will this data be available in the streaming API too?
>
> -Joel
>

[Ryan Sarver]

Ed,

Thanks for the email, answers inline below...

On Thu, Aug 20, 2009 at 2:11 PM, @epc<epcos...@gmail.com> wrote:
>
> Will twitter validate the coordinates (ie, what will the API do when I
> pass lat=777&long=-666)?
>
> If the coordinates are invalid, will the status get posted or will the
> entire request get rejected with a 4xx code?

status will get posted and invalid data will get dropped

>
> If a user has not enabled geolocating (<geo_enabled>false</
> geo_enabled>), what happens if I pass in coordinates for that user?
> Silently ignored?

correct, if geo is not enabled we will silently ignore the lat and long data

>
> Geo data will be attached to individual tweets and not users, right?
> This will have no effect on the <location> field in a user profile?

correct, the tweet-level geotagging is separate from profile-level location

> --
> -ed costello
>

[Ryan Sarver]

Joel, it will be included in the Stream API as well

[Ryan Sarver]

Ed,

Users will need to come to the website to change the setting. If we
provided an API, a misbehaving application would change the setting
without the user knowing - hence the read-only attribute.

Best, Ryan

[Nelson Minar]

Very exciting! Thanks for giving the community an early preview.

GeoRSS supports altitude and accuracy measures for point locations as
well. in GeoRSS-Simple, it's something like

<georss:point>45.256 -110.45</georss:point>
<georss:radius>500</georss:radius>
<georss:elev>313</georss:elev>

(at that lat/long, within 500 meters, at an elevation 313 meters above
the WGS84 ellipsoid).

Any plan to support that in the Twitter API? Radius is very useful for
dealing with inaccurate geolocation, and elevation (or <georss:floor>)
can help distinguish exactly where someone is.



These links may be relevant to the discussion:

W3C Geolocation API: http://dev.w3.org/geo/api/spec-source.html
(Javascript API to location. Safari supports this nicely on the
iPhone.)

iPhone CLLocation API:
http://developer.apple.com/iphone/library/documentation/CoreLocation/Reference/CLLocation_Class/CLLocation/CLLocation.html

Both APIs specify position as latittude, longitude, horizontal
accuracy, altitude, and vertical accuracy.

[mattpaul]

Very cool, Ryan, Al3x et al!

I'm sure I'm but one of many devs that can't wait to get our hands on
this 8^)

mattpaul
mopimp productions

On Aug 20, 1:46 pm, Ryan Sarver <rsar...@twitter.com> wrote:
> We wanted to give you all a heads up on a cool new feature that is coming
> soon - Geolocation. The Geolocation API will give us the ability to attach
> geographic metadata to tweets to provide additional context with your
> update. Along with the option to tag updates, we will be able to search for
> nearby tweets and view the geo metadata in user timelines. The additional
> context allows for us to deliver more meaningful and localized experiences
> to users. We are also really excited about a unique facet of this release in
> that it will be API-only initially. This means that Twitter.com won't
> surface the functionality and we look forward to seeing the new and
> interesting experiences that will grow out of the ecosystem.
>
> As part of our Geolocation efforts we will soon be publishing "Geolocation
> Best Pracitices" to guide everyone through issues like security and privacy
> as well as discussing some ideal experiences for users. Topics will include
> things like storage of location data, what to do with a user's historical
> data, how to present the concept of geotagging and more. The guide will
> create a framework from which we can address the challenges that come about
> when dealing with something as sensitive as someone's location while
> hopefully allowing everyone enough creative freedom to create their own
> experiences around it.

> It is important to note that the feature is going to be *strictly
> opt-in*. It will be disabled until a user chooses to switch it on. We

> will provide a read-only attribute
> <geo_enabled> on the user object so an app can detect if the user has it
> disabled and let them know if they need to turn it on before using a
> geolocation feature.
>
> While we can't provide an exact date for launch, you should plan on having a
> few weeks of development time before the new API is officially launched.
> With that being said, lets get to it...
>
> Example: Geotagging a Tweet
> -----------------------
> curl -d "lat=37.780467&long=-122.396762&status=I have arrived" -u user:pass
> "http://twitter.com/statuses/update.xml"
>
> <?xml version="1.0" encoding="UTF-8"?>
>
> <status>
>
> <created_at>Tue Apr 07 22:52:51 +0000 2009</created_at>
>
> ...
>

> *<geo xmlns:georss="http://www.georss.org/georss">*
>
> *<georss:point>37.780467** -122.396762**</georss:point>*
>
> *</geo>*

>
> <user>
>
> <id>1401881</id>
>
> <name>Doug Williams</name>
>
> ...
>

> *<geo_enabled>true</geo_enabled>*

>
> ...
>
> </user>
>
> </status>
>
> We have also updated the wiki to reflect what the API will look like when it

> launches, so check it out and let us know if you have any questions:http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses%C2%A0u...http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-account%C2%A0ve...

[Andriy Ivanov]

really cool! Very excited to see it!

[bg]

Ryan,

Thanks for the updates. Your example has ** after lat and lng. Is this
the proper format or some highlighting?

Thanks again,

Brad

*<georss:point>37.780467** -122.396762**</georss:point>*

[Ryan Sarver]

Nelson,

Thanks for the email and glad you picked up on GeoRSS. We don't have
any plans for this release to support georss:radius. We picked the
standard because we like the flexibility and the types of geospatial
data it can describe.

The W3C Geolocation API is close to my heart. I started the initiative
many years ago with a site called locationaware.org that ended up
being one of the forming specs for the W3C standard. We'll be using it
on m.twitter.com for launch.

As for altitude, its something we may consider in the future, but it's
a very GPS-centric attribute as alternative positioning methods like
Wifi or cellular positioning can't determine altitude.

Best, Ryan

[Ryan Sarver]

Brad,

Ah, sorry -- looks like the bolding syntax messed it up. There should
be no asterisks in the API.

Best, Ryan

[Lepton]

Perfect timing! My iPhone app about to be released has a lot to do
with geolocation, and already uses Twitter to set and see locations of
people. Myallo HotList tracks the "hotness" of people and places in
your social universe partly through their locations. For example as a
person gets nearer to you, they get hotter, if friends gather near a
place, they and the place get hotter. I want to use these upcoming
features to "discover" nearby people. You can preview the app via its
documentation at http://myallo.com/hotlist

[Sean Callahan]

Quick question Ryan, because none of this will surface on Twitter.com
will you keep the Location field for a users profile or is that going
away when this becomes love? If it stays, will there be any specific
changes regarding the location on a user's profile when this API
becomes available?

Sean

[Matt Kaufman]

Crazy I just read same sentence / tech concept in a PDF called
SocialInfluenceEC ---- thanks to the 3 publishers.

If any are here, I'd like to work with a team or group that actually
acts and defines the level such as diffusion, scoring, tracking paths,
distance, etc etc

cell 917 512 6281

On Aug 21, 2009, at 4:54 AM, Sean dCallahan <seanca...@gmail.com>
wrote:

[seang]

Cool indeed. Speaking of GeoRSS: why enclose georss:point within a new
"geo" element? Why not use georss:where?

On Aug 21, 12:32 am, Nelson Minar <nelson.mi...@gmail.com> wrote:
> Very exciting! Thanks for giving the community an early preview.
>
> GeoRSS supports altitude and accuracy measures for point locations as
> well. in GeoRSS-Simple, it's something like
>
> <georss:point>45.256 -110.45</georss:point>
> <georss:radius>500</georss:radius>
> <georss:elev>313</georss:elev>
>
> (at that lat/long, within 500 meters, at an elevation 313 meters above
> the WGS84 ellipsoid).
>
> Any plan to support that in the Twitter API? Radius is very useful for
> dealing with inaccurate geolocation, and elevation (or <georss:floor>)
> can help distinguish exactly where someone is.
>
> These links may be relevant to the discussion:
>
> W3C Geolocation API:http://dev.w3.org/geo/api/spec-source.html
> (Javascript API to location. Safari supports this nicely on the
> iPhone.)
>

> iPhone CLLocation API:http://developer.apple.com/iphone/library/documentation/CoreLocation/...

[Ben Eliott]

Hi,

Please could you advise on the differences between this and the current location based searching facility? Is the current location search based on the users location in their settings whilst this is a exact location for each tweet?

Thanks,

Ben

[@epc]

On Aug 20, 6:37 pm, Ryan Sarver <rsar...@twitter.com> wrote:
> Users will need to come to the website to change the setting. If we
> provided an API, a misbehaving application would change the setting
> without the user knowing - hence the read-only attribute.

Perfect, that’s what I’d expect. But I throw this out anyway: once
someone has opted in, would you consider adding an API method to allow
geo to be turned on/off? Or would you expect the individual
applications to allow users to mask their location when posting a
tweet?
--
-ed costello

[Mike Champion]

Very cool!

Will Twitter Search be changed to use the new geo-tweet info? Right
now if you search for "near=Boston,MA" it seems to be mostly (only?)
looking at a user's location field. I'd be curious to know if Twitter
Search will be the best place to determine tweets within a given area
and how Search will behave if my "location" is set to Boston, but my
tweet georss is in SF, for example.

Thanks,

-mike

[Raffi Krikorian]

Hi Sean.

The location field on the user's profile will be stating put!

On Aug 21, 2009, at 1:54 AM, Sean Callahan <seanca...@gmail.com>
wrote:

[Matt Kaufman]

I think that issue can be simplified down to zip code radiAl query
(simple) once you know the users relevent vicinity. It's not like
browsers are actually accurate as an actual gps (netbooks iPhone...
Chipsets will change that soon)

Anyway just throwing in here... Scaryish topic (one I play with).
What if you are celebrity + hit threat and your loc coordinates are
available no matter what (oh yeah uuuuggnkbghk!!! :)?) ---- what do
you do then? Anyway I won't post generic discussion further in this
list ---- I just started using or actually, I mean, SENDING to any
lustserv (this and cake) If I am wrong on etiquette, I apologize ---
will ttyl. :)

I'm working on a few Twitter rhings myself. I own StockAPI.com. I
imagine it might play and offer with others ;-)!!!

Thanks,
Matt Kaufman
917 512 6281

On Aug 21, 2009, at 10:36 AM, Mike Champion <mike.c...@gmail.com>
wrote:

[Cameron Kaiser]

> > Users will need to come to the website to change the setting. If we
> > provided an API, a misbehaving application would change the setting
> > without the user knowing - hence the read-only attribute.
>

> Perfect, that_s what I_d expect. But I throw this out anyway: once

> someone has opted in, would you consider adding an API method to allow
> geo to be turned on/off? Or would you expect the individual
> applications to allow users to mask their location when posting a
> tweet?

Even so, though, I don't think that would fully get around the malicious
application problem unless you could say *which* apps got to turn it on and
off, and even then ...

--
------------------------------------ personal: http://www.cameronkaiser.com/ --
Cameron Kaiser * Floodgap Systems * www.floodgap.com * cka...@floodgap.com
-- /etc/motd: /earth is 98% full. please delete anyone you can. ---------------

[Ryan Sarver]

Sean,

We hope that user.location goes back to being more static and
descriptive to where you are typically "based". In my case it will be
"SOMA, San Francisco, CA". It will provide us additional context and
be more informative to someone viewing your profile than "iPhone
(42.1234, -1221234)".

Nothing will really change about the way it works, but we expect the
behavior to change a bit.

Best, Ryan

[@epc]

On Aug 21, 11:39 am, Cameron Kaiser <spec...@floodgap.com> wrote:
> Even so, though, I don't think that would fully get around the malicious
> application problem unless you could say *which* apps got to turn it on and
> off, and even then ...

True. I guess the scenario I'm thinking of is: you've opted in, 99%
of the time you are fine with publishing your location, but this one
time you want to hide where you are tweeting from. The only option
(for now) would be to log onto twitter.com and opt-out again.

At a minimum, twitter needs to make the optin/optout work through
m.twitter.com.

As long as I'm throwing ideas out:
- What if I could tell twitter to tag my tweets with my Google
Latitude or Yahoo! FireEagle location?
- What if I could tell twitter how granular I want my location to be
(ie, even if my client publishes 40.96299,-72.13913, twitter only
stores 40.96,-72.13)
--
-ed costello

[Ryan Sarver]

Ben,

Currently we geocode your user.location data to get an idea of where
you are. That gets attached to each tweet as it comes in, but its not
usually a representation of where you were when you actually sent the
tweet. The new functionality will allow you to geotag the actual
update without modifying the user.location field.

When it comes to search, we'll use both and give priority to the
tweet-level geotag.

Make sense?

Best, Ryan

[UK]

Will this apply to direct messages too?

On Aug 21, 12:44 pm, Ryan Sarver <rsar...@twitter.com> wrote:
> Ben,
>
> Currently we geocode your user.location data to get an idea of where
> you are. That gets attached to each tweet as it comes in, but its not
> usually a representation of where you were when you actually sent the
> tweet. The new functionality will allow you to geotag the actual
> update without modifying the user.location field.
>
> When it comes to search, we'll use both and give priority to the
> tweet-level geotag.
>
> Make sense?
>
> Best, Ryan
>

> >http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses%C2%A0u...
> >http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-account%C2%A0ve...

[Damon Clinkscales]

On Aug 20, 3:46 pm, Ryan Sarver <rsar...@twitter.com> wrote:
> We wanted to give you all a heads up on a cool new feature that is coming
> soon - Geolocation.

> We have also updated the wiki to reflect what the API will look like when it
> launches, so check it out and let us know if you have any questions:http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses%C2%A0u...http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-account%C2%A0ve...
>

Ryan,

Very cool stuff. Looking forward to it.

I'm assuming that you'll update the wiki (and API when it launches)
such that
everywhere a <status> element is returned, it will contain a <geo>
element?

Thanks,
-damon

[Dean Collins]

wonder what the API would return for my current location :)
http://deancollinsblog.blogspot.com/2009/08/gogo-internet.html

________________________________

[Raffi Krikorian]

Hi Damon.

Yup - we've started updating the docs.

Generally, there will always be a <geo> in the <status> (it may just
be empty, however, if there is no geolocated information attached),
and there will always be a <geo_enabled> on every <user> which is a
boolean representing whether the user has enabled geolocation on his
or her account.

[Ben Eliott]

Hi Ryan,

Thank-you for the fast response. That makes sense, thanks a lot for
clarifying.
Wow, this is a really exciting feature.

Best Regards,

Ben

>> in. It will be disabled until a user chooses to switch it on. We

[jim.renkel]

Is there any possibility of a test site, with these API response
changes, being made available before the changes are introduced to the
real site?

This would allow us to test our sites and applications against the
test site and fix any bugs and bombs before users would otherwise
experience them when the changes go live on the real site.

My code is written very defensively and is generally OK with things
like this, but the only real way to know for sure is to test it. This
kind of testing is better done in a controlled environment than in the
real live environment.

It is not necessary that the test site accept geolocation updates,
only that it return <status> elements with <geo> sub-elements, <user>
elements with <geo_enabled> sub-elements, etc. The test site could
even have a very small user database, it wouldn't need the entire live
twitter database. Not would it need to support API requests that are
POSTs, only GETs.

Even if the test site is only available as little as 1 or 2 days
before the real site goes live, given reasonable advance notice (1
week?) as to when the test site will be available, this could greatly
smooth out the introduction of this really cool feature for all of us:
twitter, twitter partners, and twitter users.

Anything that could be done here would be greatly appreciated by me,
and I believe the whole twitter development community.

Comments expected and welcome.

Jim Renkel

On Aug 21, 11:25 pm, Raffi Krikorian <ra...@twitter.com> wrote:
> Hi Damon.
>
> Yup - we've started updating the docs.
>
> Generally, there will always be a <geo> in the <status> (it may just  
> be empty, however, if there is no geolocated information attached),  
> and there will always be a <geo_enabled> on every <user> which is a  

> boolean representing whether the user has enabledgeolocationon his  

> or her account.
>
> On Aug 21, 2009, at 6:46 PM, Damon Clinkscales <sca...@pobox.com> wrote:
>
>
>
> > On Aug 20, 3:46 pm, Ryan Sarver <rsar...@twitter.com> wrote:
> >> We wanted to give you all a heads up on a cool new feature that is  
> >> coming
> >> soon -Geolocation.

> >> We have also updated the wiki to reflect what theAPIwill look  

> >> like when it
> >> launches, so check it out and let us know if you have any  
> >> questions:http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-
> >> statuses%C2%A0u...http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-account%C2%A0ve
> >> ...
>
> > Ryan,
>
> > Very cool stuff. Looking forward to it.
>

> > I'm assuming that you'll update the wiki (andAPIwhen it launches)

[LucaPost]

so an opted-in user will have latLong data automatically attached to
her/his updates, taken from the browser/client W3c geolocation
capabilities or is it necessary to explicitly include them in the
message content?

On Aug 21, 6:44 pm, Ryan Sarver <rsar...@twitter.com> wrote:
> Ben,
>
> Currently we geocode your user.location data to get an idea of where
> you are. That gets attached to each tweet as it comes in, but its not
> usually a representation of where you were when you actually sent the
> tweet. The new functionality will allow you to geotag the actual
> update without modifying the user.location field.
>
> When it comes to search, we'll use both and give priority to the
> tweet-level geotag.
>
> Make sense?
>
> Best, Ryan
>

> >http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-statuses%C2%A0u...
> >http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-account%C2%A0ve...

[Raffi Krikorian]

its up to the API client to send that extra data along -- its not in
the tweet's textual content, if that is what you're asking. its
metadata that is "attached" to the tweet.

> so an opted-in user will have latLong data automatically attached to
> her/his updates, taken from the browser/client W3c geolocation
> capabilities or is it necessary to explicitly include them in the
> message content?
>

>> Ben,
>>
>> Currently we geocode your user.location data to get an idea of where
>> you are. That gets attached to each tweet as it comes in, but its not
>> usually a representation of where you were when you actually sent the
>> tweet. The new functionality will allow you to geotag the actual
>> update without modifying the user.location field.
>>
>> When it comes to search, we'll use both and give priority to the
>> tweet-level geotag.
>>
>> Make sense?
>>
>> Best, Ryan
>>

>>> in. It will be disabled until a user chooses to switch it on. We

--
Raffi Krikorian
Twitter Platform Team
ra...@twitter.com | @raffi

[LucaPost]

ok ok...

so I guess the Search API json response will include a:

'geo': {
"type":"Point",
"coordinates":[37.78029, -122.39697]
}

block for each of element of the 'results' array

BTW: I believe
'geo': null
would be formally more correct than
'geo': {}

for tweets missing geoLocation metadata.

[Andriy Ivanov]

any idea when API be released?