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.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 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 "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 Post contains: