Recent Places-related API enhancements & more to come...

[Taylor Singletary]

Hi Developers,

Today we're launching some of the functionality around "Places" that we announced at Chirp. You can read more about the feature here: http://blog.twitter.com/2010/06/twitter-places-more-context-for-your.html

The launch comes with a batch of API enhancements, with a number of further API additions just around the corner (like creating and updating places, obviously a crucial component for many implementors).

The documentation in this area is a honestly a bit light at the moment, but we'll be offering some more comprehensive documentation going over suggested use cases, flows, and more in the coming days.

What matters most for you:

  - GET geo/nearby_places is now GET geo/search, with some added functionality. This is a companion to GET geo/reverse_geocode, that's ideal for using in conjunction with a place selection UI.

    Read all about it at : http://bit.ly/dvNmYB

    - A query parameter called "query" lets you do textual matching when trying to find a place

    - A query parameter called "ip" lets you do a lookup based on an IP address

    - You can fine tune results with granularity, accuracy, and the contained_within parameter, which allows you to identify a place_id (matching something like a city), and only search for places within that place.

    

  - <place> tags in XML output, "place" attribute in JSON output:

  

Tweets that have a place_id associated with them can now contain some additional information not available in the past, including some attributes that further describe the location.

    

Some common place/attributes you might start seeing:

  - name

  - street_address

  - locality

  - region

  - phone

  - postal_code

  - twitter (a twitter account associated with the place)

  - cross_streets

  

Attribute key names can be variant. These are just some of the attribute keys you will see, with much more to come.

    

    Here's a quick XML representation of a status with a place:

    <status>

      <created_at>Mon Jun 14 23:30:14 +0000 2010</created_at>

      <id>16184038366</id>

      <text>I'm testing out places integrations. Can you hear me Planet Houston? I'm at the Epicenter. (psyche)</text>

      <source>web</source>

      <truncated>false</truncated>

      <in_reply_to_status_id></in_reply_to_status_id>

      <in_reply_to_user_id></in_reply_to_user_id>

      <favorited>false</favorited>

      <in_reply_to_screen_name></in_reply_to_screen_name>

      <user>

        <id>819797</id>

        <name>Taylor Singletary</name>

        <screen_name>episod</screen_name>

        <location>iPhone: 37.778181,-122.397971</location>

        <description>Reality Technician, Developer Advocate at Twitter, displeased at Planet Houston</description>

        <profile_image_url>http://a1.twimg.com/profile_images/989643540/zod_normal.jpg</profile_image_url>

        <url>http://bit.ly/5w7P88</url>

        <protected>false</protected>

        <followers_count>1461</followers_count>

        <profile_background_color>000000</profile_background_color>

        <profile_text_color>000000</profile_text_color>

        <profile_link_color>731673</profile_link_color>

        <profile_sidebar_fill_color>007ffe</profile_sidebar_fill_color>

        <profile_sidebar_border_color>bb0e79</profile_sidebar_border_color>

        <friends_count>1420</friends_count>

        <created_at>Wed Mar 07 22:23:19 +0000 2007</created_at>

        <favourites_count>254</favourites_count>

        <utc_offset>-28800</utc_offset>

        <time_zone>Pacific Time (US &amp; Canada)</time_zone>

        <profile_background_image_url>http://a3.twimg.com/profile_background_images/19651315/fiberoptics.jpg</profile_background_image_url>

        <profile_background_tile>true</profile_background_tile>

        <notifications>false</notifications>

        <geo_enabled>true</geo_enabled>

        <verified>false</verified>

        <following>false</following>

        <statuses_count>6477</statuses_count>

        <lang>en</lang>

        <contributors_enabled>false</contributors_enabled>

      </user>

      <geo/>

      <coordinates/>

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

        <id>a851ec943d3a27c5</id>

        <name>Epicenter Cafe</name>

        <full_name>Epicenter Cafe, San Francisco</full_name>

        <place_type>poi</place_type>

        <url>http://api.twitter.com/1/geo/id/a851ec943d3a27c5.json</url>

        <attributes>

          <attribute>

            <key>street_address</key>

            <value>764 Harrison St</value>

          </attribute>

        </attributes>

        <bounding_box>

          <georss:polygon>37.781343 -122.399142 37.781343 -122.399142 37.781343 -122.399142 37.781343 -122.399142</georss:polygon>

        </bounding_box>

        <country code="US">The United States of America</country>

      </place>

      <contributors/>

      <annotations/>

    </status>

    

    And here's the JSON representation:

    {

        "in_reply_to_user_id": null,

        "geo": null,

        "source": "web",

        "created_at": "Mon Jun 14 23:30:14 +0000 2010",

        "place": {

            "place_type": "poi",

            "country_code": "US",

            "attributes": {

                "street_address": "764 Harrison St"

            },

            "country": "The United States of America",

            "full_name": "Epicenter Cafe, San Francisco",

            "url": "http://api.twitter.com/1/geo/id/a851ec943d3a27c5.json",

            "name": "Epicenter Cafe",

            "id": "a851ec943d3a27c5",

            "bounding_box": {

                "type": "Polygon",

                "coordinates": [[[ - 122.399142, 37.781343], [ - 122.399142, 37.781343], [ - 122.399142, 37.781343], [ - 122.399142, 37.781343]]]

            }

        },

        "in_reply_to_screen_name": null,

        "favorited": false,

        "truncated": false,

        "annotations": null,

        "user": {

            "profile_background_image_url": "http://a3.twimg.com/profile_background_images/19651315/fiberoptics.jpg",

            "profile_image_url": "http://a1.twimg.com/profile_images/989643540/zod_normal.jpg",

            "description": "Reality Technician, Developer Advocate at Twitter, displeased at Planet Houston",

            "lang": "en",

            "statuses_count": 6477,

            "profile_sidebar_fill_color": "007ffe",

            "profile_background_tile": true,

            "screen_name": "episod",

            "contributors_enabled": false,

            "profile_sidebar_border_color": "bb0e79",

            "following": false,

            "geo_enabled": true,

            "notifications": false,

            "created_at": "Wed Mar 07 22:23:19 +0000 2007",

            "followers_count": 1460,

            "friends_count": 1420,

            "verified": false,

            "profile_background_color": "000000",

            "favourites_count": 254,

            "protected": false,

            "url": "http://bit.ly/5w7P88",

            "profile_text_color": "000000",

            "name": "Taylor Singletary",

            "time_zone": "Pacific Time (US & Canada)",

            "location": "iPhone: 37.778181,-122.397971",

            "id": 819797,

            "utc_offset": -28800,

            "profile_link_color": "731673"

        },

        "in_reply_to_status_id": null,

        "coordinates": null,

        "id": 16184038366,

        "contributors": null,

        "text": "I'm testing out places integrations. Can you hear me Planet Houston? I'm at the Epicenter. (psyche)"

    },

    

Stay tuned for more information in the coming days and weeks on how to create places, more about how attributes about places work, and much more!

Thanks,

Taylor

[Ramanean]

Whether it would be better to use authentication for it?

Thanks
Shan

On Jun 15, 4:43 am, Taylor Singletary <taylorsinglet...@twitter.com>
wrote:

> Hi Developers,
>
> Today we're launching some of the functionality around "Places" that we

> announced at Chirp. You can read more about the feature here:http://blog.twitter.com/2010/06/twitter-places-more-context-for-your....

[tsmango]

I can't really test this right now because geo services are currently
disabled, but does this mean that the geo/reverse_geocode and geo/
search api methods both return "places" in addition to neighborhoods
and cities now? I understand they are all technically "places" but I
mean business entities alongside neighborhoods and cities. Are they
all mixed together now? If so, is there a way to get either business
listings *or* geographic regions?

I understand you guys now own GeoAPI so you're probably coming from a
similar point of view and I realize that their entities are nested, as
in a business is contained within some geographic region, yet both are
considered entities.

Anyhow, as you said, the documentation is kind of light for geo/search
so I'm just a bit confused as to the data that's actually returned.
Unfortunately, the application and service I work on has been using
geo/reverse_geocode for a while now to attach cities (specifically
cities) to tweets that run through our service and we've been planning
to submit our app to Apple tomorrow.

Thank you very much, in advance.

On Jun 14, 7:43 pm, Taylor Singletary <taylorsinglet...@twitter.com>
wrote:

> Hi Developers,
>
> Today we're launching some of the functionality around "Places" that we

> announced at Chirp. You can read more about the feature here:http://blog.twitter.com/2010/06/twitter-places-more-context-for-your....

[tsmango]

Just to answer my own question in case others were wondering, what I
found was that:

If you use geo/reverse_geocode, you can specify the granularity as
either 'city' or 'neighborhood'. The default is 'neighborhood'. Places
are never returned. The documentation states that this endpoint "will
deliver generalized results about geography".

If you use geo/search, you can specify the granularity as either
'city', 'neighborhood' or 'poi' (not actually documented). The default
is 'neighborhood'. The documentation for this method states that this
is the preferred method for allowing users to select a place to attach
to their tweet.

Anyhow, probably should have waited until the geo services were turned
back on the other day before posting my questions. Sorry for the
trouble and hope the granularity option of "poi" helps others.

[Taylor Singletary]

Thanks for sharing your tips. I'll make sure this is all covered in
the expanded documentation I'm working on!

[harrisj]

Hello,

Currently, using places doesn't modify the 'geo' field. This makes
sense for neighborhoods or cities, because picking a centroid is a
little arbitrary and those users might get freaked out if we place
them at a specific point on a map. However, I would argue that this
behavior is counterintuitive when we get to the 'poi' level. When I
pick the building I'm in on twitter.com, I'm assuming I'm geocoding my
location (and providing some additional semantic information beyond
lat/lng). However, this doesn't seem to be the case. Would we consider
changing this?

Furthermore, will any place-annotated tweets show up in the streaming
API when using the locations query parameters? Or is that only limited
to explicitly geotagged tweets?

Thanks,
Jacob

[David Helder]

The geo field is the user's (or tweet's) exact location. The place
field, whether a POI, neighborhood, city, or admin, contains the
place's location. Today POIs are always points, but in the future
there may be some polygons (e.g. stadiums, malls, amusement parks).
In this case the exact location would matter.

A place-annotated tweet will show up in the streaming API, even if
it doesn't have an exact location.

David
Twitter Geo Team

[zn...@borasky-research.net]

Quoting David Helder <da...@twitter.com>:

> The geo field is the user's (or tweet's) exact location. The place
> field, whether a POI, neighborhood, city, or admin, contains the
> place's location. Today POIs are always points, but in the future
> there may be some polygons (e.g. stadiums, malls, amusement parks).
> In this case the exact location would matter.
>
> A place-annotated tweet will show up in the streaming API, even if
> it doesn't have an exact location.
>
> David
> Twitter Geo Team

The POI data I've collected show that they are coded as four-sided
polygons even if they are points, with all four "corners" of the
polygon being equal to the "point". And sometimes the "geo" field is
present and sometimes it isn't. And sometimes the "coordinates" field
is present and sometimes it isn't. IIRC the geo and coordinates field
have latitude first and longitude second, but it's the other way
around for the "corners" of polygons!

Can we get this stuff documented so I'm not writing code that matches
things that will change? And so I can file bugs when something doesn't
work, like searching for places? Conversely, is there value in an open
source library that monitors the "sample" streaming API and announces
to the world when Twitter starts sending something new or starts
sending stuff in a new format? ;-)

I've been in the "industry" a long time - normally Twitter's pretty
good about announcing major changes, but "little stuff" like geo data
formats tends to just get changed without documentation and sometimes
without even warnings. In the case of User Streams, we *know* it's a
developer preview and subject to change. But something like places is
a *released* feature, and I think that kind of thing should happen
*with* documentation on or preferably *before* release.

[Joe Critchley]

Hi,

In terms of both technicalities and appropriate semantics,
will it be ok to use the attached 'place' to
annotate past or future places, as well as the present location?

This could play a key part in my development, so any help would be
great. Thanks.

On Jun 14, 7:43 pm, Taylor Singletary <taylorsinglet...@twitter.com>
wrote:

> Hi Developers,
>
> Today we're launching some of the functionality around "Places" that we

> announced at Chirp. You can read more about the feature here:http://blog.twitter.com/2010/06/twitter-places-more-context-for-your....

>       <created_at>Mon Jun 14 23:30:14+0000 2010</created_at>

>         <created_at>Wed Mar 07 22:23:19+0000 2007</created_at>

>         "created_at": "Mon Jun 14 23:30:14+0000 2010",

>             "created_at": "Wed Mar 07 22:23:19+0000 2007",