Developer terms

Geo guidelines

Last Update: October 22, 2014.



Tweeting With Location is the geotagging feature in the Twitter API. This feature helps to 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 always accompanies a Tweet — you may wish to display only place names (place_ids) and allow users to further opt in to exact latitude and longitude on a per-Tweet basis or as a specific alternative setting.
  • When you access your users’ location data to post a Tweet, that information should not be stored by you apart from the Tweet without the user’s explicit permission.
  • 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 latitude and longitude is part of the information (or the only 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 turn on and off their location each time they compose a Tweet.
  • You must follow the terms of Twitter’s Developer Policy – including the requirement that you may not aggregate, cache, or store location data and other geographic information from the Twitter API, except as part of a Tweet, and may not use such location data or geographic information on a standalone basis.

Specific Examples

Example 1: No addition of explicit latitude and longitude (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. Make sure the user knows if exact location information will be displayed.
  6. Allow the user the choice to turn on or off location with every Tweet compose.

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 latitude and longitude and display the place_ID in addition to lat/lon for areas where we have data available.

Ensure that it is transparent to your users that their exact coordinates are being used and displayed on Twitter. A best practice for existing apps would be to allow users to turn on or off their location on a per-Tweet basis. You can also enable your users to share only place_IDs instead of exact coordinates as a 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. Users can clear location data from their Tweets by clicking the “clear my location history” button on the Settings page as described here).


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 contact us.