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 "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": {
}
}
}
Next Steps
Explore the other sub-objects that a Tweet contains: