Geo Objects

Tweets can be associated with a location, generating a Tweet that has been ‘geo-tagged.’ Tweet locations can be assigned by using the Twitter user-interface or when posting a Tweet using the API. Tweet locations can be an exact ‘point’ location, or a Twitter 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 Tweet: 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 Tweet is geo-tagged with a place,. Places are specific, named locations with corresponding geo coordinates. When users decide to assign a location to their Tweet, they are presented with a list of candidate Twitter Places. When using the API to post a Tweet, a Twitter Place can be attached by specifying a place_id when posting the Tweet. Tweets 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 Tweet 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 Twitter 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.twitter.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 Tweets with exact coordinates. Example:

"type":"Polygon"

Geo object data dictionary

Field Type Description
coordinates Collection of Float

The longitude and latitude of the Tweet’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 Tweet coordinates fields. Example:

 

 

"type": "Point"

 

 

 

Coordinates object data dictionary

Field Type Description
coordinates Collection of Float

The longitude and latitude of the Tweet’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 Tweet 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.twitter.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.twitter.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": {
      
    }
  }
}
    
Was this document helpful?
Thank you

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?
Thank you for the feedback. Your comments will help us improve our documents in the future.