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.

FieldTypeDescription
attributesObjectContains 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_boxObjectA 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"}
countryStringName of the country containing this place.

Example:

"country":"France"
country_codeStringShortened country code representing the country containing this place.

Example:

"country_code":"FR"
full_nameStringFull human-readable representation of the place’s name.

Example:

"full_name":"San Francisco, CA"
idStringID representing this place. Note that this is represented as a string, not an integer.

Example:

"id":"7238f93a3e899af6"
nameStringShort human-readable representation of the place’s name.

Example:

"name":"Paris"
place_typeStringThe type of location represented by this place.

Example:

"place_type":"city"
urlStringURL representing the location of additional place metadata for this place.

Example:

"url":"https://api.twitter.com/1.1/geo/id/7238f93a3e899af6.json"

Bounding box

FieldTypeDescription
coordinatesArray of Array of Array of FloatA 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] ] ]
typeStringThe 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.

KeyDescription
street_address
localitythe city the place is in
regionthe administrative region the place is in
iso3the country code
postal_codein the preferred local format for the place
phonein the preferred local format for the place, include long distance code
twittertwitter screen-name, without @
urlofficial/canonical URL for place
app:idAn 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": "US",
  "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"
}