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 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"
}