Skip to main content
Last Update: October 29, 2026.

​
Introduction

Posting with location is the geotagging feature in the X API. This feature helps to provide a more meaningful experience for users by making Posts more contextual. For instance, “Fireworks!” is much more relevant when associated with a location: “Fireworks!” from the SoMa Neighborhood in San Francisco, California. This page explains how to give users control over their location when your app posts on their behalf, and how location data works in X API v2.

​
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 “posting 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 posting with location (turn location “on”) before your app adds a location to their Posts.
  • When you access your users’ location data to add a location to a Post, that information should not be stored by you apart from the Post without the user’s explicit permission.
  • It must be clear to users what location information, if any, will be displayed in association with their Post. One way you can do this is by showing the user the place that will be attached, such as its name or a map, before the Post is published.
  • Users should be able to turn their location on and off each time they compose a Post.
  • You must follow the terms of X’s Developer Policy, including the requirement that you may not (and may not permit others to) store, aggregate, or cache location data and other geographic information contained in X Content, except as part of a Post, and may not use such location data or geographic information on a standalone basis.

​
Posting with location in X API v2

To add a location when you create a Post, include a geo object with a place_id in the POST /2/tweets request body. For example, this request tags the Post with Manhattan, NY (place ID 01a9a39529b27f36):
  • geo.place_id is the only location field the endpoint accepts. You can’t send latitude and longitude coordinates, so a Post created through the API can only be tagged with a place.
  • place_id takes the ID of an X place, the same identifier returned as id on a Place object. X API v2 has no places search or reverse geocode endpoint, so take place IDs from existing Posts: request the geo.place_id expansion with place.fields (for example, expansions=geo.place_id&place.fields=full_name,id) and reuse the id of the returned Place object.
  • The location is attached only if the posting user has geo enabled in their profile settings. If they don’t, the Post is still created, but without the location. See Profile settings.
A compose flow that follows these guidelines looks like this:
  1. Show an “Add your location” option when the user composes a Post, and leave location off until the user turns it on.
  2. Before the Post is published, show the user the place that will be attached, and let them remove it.
  3. When the user publishes, send the place’s ID as geo.place_id.
  4. Let the user turn location on or off each time they compose a Post.

​
Reading location from Posts

For a geotagged Post, the geo field can contain:
  • place_id: the ID of the tagged place.
  • coordinates: exact coordinates, when present, as a GeoJSON Point whose coordinates array is [longitude, latitude].
geo isn’t returned by default; request it as a Post field. To get details about the tagged place, add the geo.place_id expansion. The Place object is returned in includes.places with its default fields, id and full_name. Use place.fields to request more, such as name, place_type, country, country_code, contained_within, and geo, which is the place’s bounding box as a GeoJSON Feature.
See the Place object reference for the full response. Location data you read from Posts is subject to the same Developer Policy restrictions: keep it with the Post it belongs to, and don’t use it on a standalone basis.

​
X storage of user location data

X saves all the location data that a user chooses to publicly display with a Post. This is similar to how X stores the time stamp that says when the Post was made, meaning if a Post includes exact coordinates, X stores this exact location along with the Post for as long as the Post exists. Users can remove location information from their Posts, as described in this Help Center article. If you store Posts, the Developer Policy’s content compliance rules require you to update your copies when location information is removed from them. Batch compliance results report these changes with the scrub_geo action.

​
Summary

The addition of location to a Post adds an enormous amount of context and value from a user perspective. However, implementations of location in your app should take privacy and user transparency as key considerations in designing a location-focused product. If you have any questions or comments about privacy, location, and other geo features, please contact us.