Foursquare location data in the API


#1

Just a few months after Twitter first launched in 2006, we released the Twitter API to help developers build experiences on top of Twitter. Over the years, we’ve made a variety of real-time data – available only on Twitter – accessible via our API. And today, we’re taking real-time, location-based data to a whole new level.

Through our recent partnership with Foursquare, Twitter users in the U.S. and Canada can now geotag their Tweets with a precise location (e.g., “Bob’s Restaurant”) rather than a simple geographic location (e.g., “San Francisco, CA”). For those of you building location-based services integrated with Twitter, you can empower your users to share their moments at specific places and have more control over their location sharing, thereby building a stickier user experience for your services.



With the new place data through our API, you can now associate individual Tweets with specific venues, powered by Foursquare. Latitude and longitude coordinates of these sites are even more specific than our previous support through latitude and longitude bounding boxes. If you’re building a platform to monitor or analyze location-based social media, you’ll be able to access more specific and contextual location-based data.

No code change necessary

When a user selects a Foursquare-powered venue within their Tweet, the “place” section of the Tweet data payload will include the place ID, place name, and lat/long coordinates of the venue. All of these payload changes are backward compatible. and will not result in any changes to the structure of the Tweet payload, so no need to worry about that!

See our sample payload below of a Tweet associated with a venue for more details. The “place” object within the Tweet payload contains all the information about the place being tagged.

These are the unique fields that are noteworthy:

  1. “id”: “07d9dafd5dc82004”, a unique identifier for the place

  2. “url”: “https://api.twitter.com/1.1/geo/id/07d9dafd5dc82004.json

  3. “place_type” : The type of place being tagged, for example “poi” relates to point of interest. It can also take values like country, neighborhood, city, and admin

  4. “bounding_box”: Geo fenced polygon indicating the latitude and longitude coordinates of the place. It includes 4 coordinate values

  5. “country_code”: “US”

  6. “country”: “United States”

  7. “name”: Short human-readable representation of the place’s name

  8. “full_name”: Detailed human-readable representation of the place’s name

{
    "created_at": "Sun Feb 22 15:32:35 +0000 2015",
    "id": 569520133850452000,
    "id_str": "569520133850451968",
    "text": "NYC doing its best @KarlTheFog impression at the Empire State Building last night. http://t.co/TS1vQySWdM",
    "source": "<a href=\"http://twitter.com\" rel=\"nofollow\">Twitter for  iPhone</a>",
    "truncated": false,
    "in_reply_to_status_id": null,
    "in_reply_to_status_id_str": null,
    "in_reply_to_user_id": null,
    "in_reply_to_user_id_str": null,
    "in_reply_to_screen_name": null,
    "user": {
     ...
    },
    "place": {
        "id": "07d9dafd5dc82004",
        "url": "https://api.twitter.com/1.1/geo/id/07d9dafd5dc82004.json",
        "place_type": "poi",
        "name": "Empire State Building",
        "full_name": "Empire State Building",
        "country_code": "US",
        "country": "United States",
        "bounding_box": {
            "type": "Polygon",
            "coordinates": [
                [
                    [
                        -73.98488498889492,
                        40.74815422067702
                    ],
                    [
                        -73.98488498889492,
                        40.74815422067702
                    ],
                    [
                        -73.98488498889492,
                        40.74815422067702
                    ],
                    [
                        -73.98488498889492,
                        40.74815422067702
                    ]
                ]
            ]
        },
        "attributes": {}
    },
    "contributors": null,
    "retweet_count": 0,
    "favorite_count": 0,
    "entities": {
    ...
    },
    "extended_entities": {
    ...
    },
    "favorited": false,
    "retweeted": false,
    "possibly_sensitive": false,
    "filter_level": "low",
    "lang": "en",
    "timestamp_ms": "1424619155739"
}

The addition of Foursquare-powered venues improves the quality of geo place data, which we expect to become the primary type of location data associated with a Tweet. We want to focus the experience around the location that the user is geotagging vs. the user’s precise coordinates. Now that users can geotag many more granular locations (say, the espresso shop on the corner), we’re making it optional for users to also provide their own coordinates. This means that the coordinates of the “place” will always be associated with the Tweet and the coordinates of the user will sometimes be associated with the Tweet. As a result, we expect the richness of the user experience and the data to increase on the aggregate, but the number of user coordinates tied to a Tweet to decrease significantly.

Whether you’re building a real-time broadcasting app for consumers or a location-based social media analytics platform, our new geo-tagging support will help you increase engagement and deliver you more precise, powerful data.

To learn more about the changes, please see our full docs on the places object.


Search API returning (very) sparse geocode results
80% reduction in tweets with coordinate data
#2