Geo objects

Geo Objects

Posts can be associated with a location, generating a Post that has been ‘geo-tagged.’ Post locations can be assigned by using the X user-interface or when posting a Post using the API. Post locations can be an exact ‘point’ location, or a X Place with a ‘bounding box’ that describes a larger area ranging from a venue to an entire region.

There are three ‘root-level’ JSON objects used to describe the location associated with a Post: place, geo and coordinates

Additionally, the native enriched format includes the profile geo enrichment's derived location within the user object.

The place object is always present when a Post is geo-tagged with a place,. Places are specific, named locations with corresponding geo coordinates. When users decide to assign a location to their Post, they are presented with a list of candidate X Places. When using the API to post, a X Place can be attached by specifying a place_id when posting. Posts associated with Places are not necessarily issued from that location but could also potentially be about that location.

The geo and coordinates objects only present (non-null) when the Post is assigned an exact location. If an exact location is provided, the coordinates object will provide a [long, lat] array with the geographical coordinates, and a X Place that corresponds to that location will be assigned.

Place data dictionary

Field Type Description
id String

ID representing this place. Note that this is represented as a string, not an integer. Example:

"id":"01a9a39529b27f36"
url String

URL representing the location of additional place metadata for this place. Example:

"url":"https://api.x.com/1.1/geo/id/01a9a39529b27f36.json"
place_type String

The type of location represented by this place. Example:

"place_type":"city"
name String

Short human-readable representation of the place’s name. Example:

"name":"Manhattan"
full_name String

Full human-readable representation of the place’s name. Example:

"full_name":"Manhattan, NY"
country_code String

Shortened country code representing the country containing this place. Example:

"country_code":"US"
country String

Name of the country containing this place. Example:

"country":"United States"
bounding_box Object

A bounding box of coordinates which encloses this place. Example:

{
  "bounding_box": {
    "coordinates": [
      [
        [
          -74.026675,
          40.683935
        ],
        [
          -74.026675,
          40.877483
        ],
        [
          -73.910408,
          40.877483
        ],
        [
          -73.910408,
          40.3935
        ]
      ]
    ],
    "type": "Polygon"
  }
}
attributes Object

When using PowerTrack, 30-Day and Full-Archive Search APIs, and Volume Streams this hash is null. Example:

"attributes": {}

Bounding box

Field Type Description
coordinates Array of Array of Array of Float

A series of longitude and latitude points, defining a box which will contain the Place entity this bounding box is related to. Each point is an array in the form of [longitude, latitude]. Points are grouped into an array per bounding box. Bounding box arrays are wrapped in one additional array to be compatible with the polygon notation. Example:

{
  "coordinates": [
    [
      [
        -74.026675,
        40.683935
      ],
      [
        -74.026675,
        40.877483
      ],
      [
        -73.910408,
        40.877483
      ],
      [
        -73.910408,
        40.3935
      ]
    ]
  ]
}
type String

The type of data encoded in the coordinates property. This will be “Polygon” for bounding boxes and “Point” for Posts with exact coordinates. Example:

"type":"Polygon"

Geo object data dictionary

Field Type Description
coordinates Collection of Float

The longitude and latitude of the Post's location, as a collection in the form [latitude, longitude]. Example:

 

 

  "geo": {

    "type": "Point",

    "coordinates": [

      54.27784,

      -0.41068

    ]

  }

 

 

type String

The type of data encoded in the coordinates property. This will be “Point” for Post coordinates fields. Example:

 

 

"type": "Point"

 

 

 

Coordinates object data dictionary

Field Type Description
coordinates Collection of Float

The longitude and latitude of the Post's location, as a collection in the form [longitude, latitude]. Example:


  "coordinates": {

    "type": "Point",

    "coordinates": [

      -0.41068,

      54.27784

    ]

  }

type String

The type of data encoded in the coordinates property. This will be “Point” for Post coordinates fields. Example:

"type": "Point"

Derived locations

Field Type Description
derived locations object

Derived location from the profile geo enrichement

    "derived": {

      "locations": [

        {

          "country": "United Kingdom",

          "country_code": "GB",

          "locality": "Yorkshire",

          "region": "England",

          "full_name": "Yorkshire, England, United Kingdom",

          "geo": {

            "coordinates": [

              -1.5,

              54

            ],

            "type": "point"

          }

        }

      ]

    }

Examples:

      {
  "geo": null,
  "coordinates": null,
  "place": {
    "id": "07d9db48bc083000",
    "url": "https://api.x.com/1.1/geo/id/07d9db48bc083000.json",
    "place_type": "poi",
    "name": "McIntosh Lake",
    "full_name": "McIntosh Lake",
    "country_code": "US",
    "country": "United States",
    "bounding_box": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -105.14544,
            40.192138
          ],
          [
            -105.14544,
            40.192138
          ],
          [
            -105.14544,
            40.192138
          ],
          [
            -105.14544,
            40.192138
          ]
        ]
      ]
    },
    "attributes": {
      
    }
  }
}
    
      {
  "geo": {
    "type": "Point",
    "coordinates": [
      40.74118764,
      -73.9998279
    ]
  },
  "coordinates": {
    "type": "Point",
    "coordinates": [
      -73.9998279,
      40.74118764
    ]
  },
  "place": {
    "id": "01a9a39529b27f36",
    "url": "https://api.x.com/1.1/geo/id/01a9a39529b27f36.json",
    "place_type": "city",
    "name": "Manhattan",
    "full_name": "Manhattan, NY",
    "country_code": "US",
    "country": "United States",
    "bounding_box": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -74.026675,
            40.683935
          ],
          [
            -74.026675,
            40.877483
          ],
          [
            -73.910408,
            40.877483
          ],
          [
            -73.910408,
            40.683935
          ]
        ]
      ]
    },
    "attributes": {
      
    }
  }
}