Places¶
Places are specific, named locations with corresponding geo coordinates. They can be attached to Tweets by specifying a place_id
when tweeting. Tweets associated with places are not necessarily issued from that location but could also potentially be about that location. Places can be searched
for. Tweets can also be found by place_id.
Places also have an attributes field that further describes a Place. These attributes are more convention rather than standard practice, and reflect information captured in the Twitter places database. See Place Attributes for more information.
Field Guide¶
Consumers of Places should tolerate the addition of new fields and variance in ordering of fields with ease. Not all fields appear in all contexts. It is generally safe to consider a nulled field, an empty set, and the absence of a field as the same thing.
Field | Type | Description |
attributes | Object | Contains a hash of variant information about the place. See Place Attributes for more detail. Example: "attributes": {
"street_address": "795 Folsom St",
"623:id": "210176",
"twitter": "twitter"
},
|
bounding_box | Object | A bounding box of coordinates which encloses this place. Example: "bounding_box":{"coordinates":[ [ [2.2241006,48.8155414], [2.4699099,48.8155414], [2.4699099,48.9021461], [2.2241006,48.9021461] ] ], "type":"Polygon"}
|
country | String | Name of the country containing this place. Example: "country":"France"
|
country_code | String | Shortened country code representing the country containing this place. Example: "country_code":"FR"
|
full_name | String | Full human-readable representation of the place’s name. Example: "full_name":"San Francisco, CA"
|
id | String | ID representing this place. Note that this is represented as a string, not an integer. Example: "id":"7238f93a3e899af6"
|
name | String | Short human-readable representation of the place’s name. Example: "name":"Paris"
|
place_type | String | The type of location represented by this place. Example: "place_type":"city"
|
url | String | URL representing the location of additional place metadata for this place. Example: "url":"https://api.twitter.com/1.1/geo/id/7238f93a3e899af6.json"
|
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":[ [ [2.2241006,48.8155414], [2.4699099,48.8155414], [2.4699099,48.9021461], [2.2241006,48.9021461] ] ]
|
type | String | The type of data encoded in the coordinates property. This will be “Polygon” for bounding boxes. Example: "type":"Polygon"
|
Place Attributes¶
Place Attributes are metadata about places. An attribute is a key-value pair of arbitrary strings, but with some conventions.
Below are a number of well-known place attributes which may, or may not exist in the returned data. These attributes are provided when the place was created in the Twitter places database.
Key | Description |
street_address | |
locality | the city the place is in |
region | the administrative region the place is in |
iso3 | the country code |
postal_code | in the preferred local format for the place |
phone | in the preferred local format for the place, include long distance code |
twitter screen-name, without @ | |
url | official/canonical URL for place |
app:id | An ID or comma separated list of IDs representing the place in the applications place database. |
Keys can be no longer than 140 characters in length. Values are unicode strings and are restricted to 2000 characters.
Place Attributes Examples¶
The following example would require OAuth authentication when performing in API v1.1.
curl https://api.twitter.com/1.1/geo/id/247f43d441defc03.json
{
"name": "Twitter HQ",
"polylines": [
],
"country": "United States",
"country_code": "wUS",
"attributes": {
"street_address": "795 Folsom St",
"623:id": "210176",
"twitter": "twitter"
},
"url": "https://api.twitter.com/1.1/geo/id/247f43d441defc03.json",
"bounding_box": {
"coordinates": [
[
[
-122.400612831116,
37.7821120598956
],
[
-122.400612831116,
37.7821120598956
],
[
-122.400612831116,
37.7821120598956
],
[
-122.400612831116,
37.7821120598956
]
]
],
"type": "Polygon"
},
"id": "247f43d441defc03",
"contained_within": [
{
"name": "San Francisco",
"country": "United States",
"country_code": "US",
"attributes": {
},
"url": "https://api.twitter.com/1.1/geo/id/5a110d312052166f.json",
"bounding_box": {
"coordinates": [
[
[
-122.51368188,
37.70813196
],
[
-122.35845384,
37.70813196
],
[
-122.35845384,
37.83245301
],
[
-122.51368188,
37.83245301
]
]
],
"type": "Polygon"
},
"id": "5a110d312052166f",
"full_name": "San Francisco, CA",
"place_type": "city"
}
],
"full_name": "Twitter HQ, San Francisco",
"geometry": {
"coordinates": [
-122.400612831116,
37.7821120598956
],
"type": "Point"
},
"place_type": "poi"
}