Geo Developer Guidelines

Introduction

Tweeting With Location is the next version of the geotagging feature in the Twitter API. We now convert lat/lon coordinates into actual places (in particular, neighborhoods and cities). This helps provide a more meaningful experience for users by making tweets more contextual. For instance, "Fireworks!" is much more relevant when associated with a location: "Fireworks!" from the SOMA Neighborhood in San Francisco, California. We look forward to working with the developer ecosystem to create great experiences around this functionality!

User Privacy And User Control Of Their Location Information

To ensure a good and safe experience, developers should be sensitive to user privacy when dealing with their location as well as provide baseline consistency in the "Tweeting with Location" experience. Here are some key things to keep in mind that help protect user privacy and ensure users understand the impact of their actions:

General Guidelines

  • Users must opt-in to use the Tweeting With Location feature (turn location "on").
  • Users must give explicit permission for their exact location to be displayed with their tweets. If the location feature on your client is "sticky" — i.e. once location is turned on it is always broadcast, the recommended default level is to display only place_ids and allow users to further opt in to exact lat/lon on a per tweet basis or as a specific alternative setting. If you have an existing implementation that only has lat/lon coordinates displayed, you should ensure that new users understand that their exact location will be added to tweets.
  • It must be clear to users what level of location information, if any, will be displayed in association with their tweet. One way you can do this is by showing a map of how this information will be displayed before the tweet is published. If exact lat/lon is part of the information published by the user on the client, it should be clear to the user that their exact coordinates will be published.
  • Users should be able to refresh or change their location before tweeting.
  • Users should be able to clear their location per tweet.

Specific Examples

Example 1: No addition of explicit lat/lon (this is the current Twitter Web Client UI)

  1. Show a link to "Add your location" when a user composes a tweet
  2. In the background, use the Twitter reverse_geocode API call and pass the latitude, longitude, accuracy of your fix, and the user's preferred granularity (which, by default, is "neighborhood");
  3. Display the name for the default place (Twitter will attempt to order these in a way that makes sense - the ordering is such that a Twitter client can just display the list without a need for modification);
  4. Allow the user to select a different location from the list (e.g. change from "SoMa, San Francisco" to "South Beach, San Francisco").
  5. Important: Be transparent with the user if you will be displaying exact location information. Give the user an option to opt out of displaying exact lat/lon coordinates; Make sure this is explicit so the user knows if exact location information will be displayed.
  6. Allow the user to clear location with every Tweet.

Example 2: Existing geotagging implementations

A number of Twitter client apps have the original geotagging feature (which only broadcast lat/lons without providing place_IDs) implemented. The default behavior of the API mimics this behavior – i.e. as a developer you do not need to make any changes to your existing app in order to maintain the behavior that exists today. Indeed, if you simply pass a lat/lon coordinate in to Twitter, Twitter will automatically reverse geocode that lat/lon and display the place_ID for areas for which we have data available.

The key from a user privacy perspective is to ensure that it is transparent to users that their exact coordinates are being used and displayed on Twitter. A best practice for existing apps would be to allow users to "clear" their exact coordinates on a per tweet basis, as well as choose to display only place_IDs instead of exact coordinates as their default, "sticky" setting.

Twitter Storage Of User Location Data

Twitter will store data passed by the client as follows:

  • Twitter will save all the data that a user chooses to publicly display to his/ her followers. This is similar to how Twitter stores the time stamp that says when the Tweet was made, meaning if a user Tweets with their exact coordinates, Twitter will store this exact location along with the Tweet for as long as the Tweet exists (or until you click the "clear my location history" button on the Settings page as described here.)
  • If a user turns on tweeting with location but chooses to not include the exact coordinates in a tweet, Twitter will not display this information to their followers. While Twitter will not display this information in a user’s timeline, it may temporarily store exact points for 6 months.

Summary

The addition of location to a tweet adds an enormous amount of context and value from a user perspective. However, implementations of location in your client should be careful to take privacy and user transparency as a key consideration in designing a location-focused product.

If you have any questions or comments about privacy, location, and other geo features, please email api@twitter.com