Places とは、地理座標に対応する特定の名前を付けた場所情報のことです。
これらはつぶやく際にplace_idを設定することで ツイートに付与できます。
Placesに関連するツイートは必ずその場所から発行されているわけではなく、何らかの形でその場所と関連している程度の場合もあります。
Placesは 検索対象にすることができます。
またPlacesはplace_idで調べることもできます。
またPlacesは場所の情報を記述するためのフィールド属性を持っています。これらの属性は標準のやり方よりも convention なもので、Twitter のplaceデータベース内に格納されている情報が使用されています。詳細についてはPlace 属性 を参照してください。
Placesを使用する際には、新たにフィールドが追加されるケースやフィールドの並び順がばらばらになるケースを想定してプログラムを組む必要があります。 コンテクストによっては表示されないフィールドもあります。フィールドがnullになっている、emptyと設定されている、フィールド自体が存在しないといった事象は全て同じものと考えて処理を組むのが安全です。
| Field | 型 | 説明 |
|---|---|---|
| attributes | Object |
placeに関するバリアント型情報のハッシュを保持しています。詳細についてはPlace 属性を参照してください。 例: "attributes": {
"street_address": "795 Folsom St",
"623:id": "210176",
"twitter": "twitter"
},
|
| bounding_box | Object |
この例を囲む座標の領域範囲。
例: "bounding_box":{"coordinates":[ [ [2.2241006,48.8155414], [2.4699099,48.8155414], [2.4699099,48.9021461], [2.2241006,48.9021461] ] ], "type":"Polygon"}
|
| country | String |
このplaceが属する国の名前
例: "country":"France" |
| country_code | String |
このplaceが属する国の名前を表す短縮された国コード
例: "country_code":"FR" |
| full_name | String |
place名を人にも読める形でフル表記したもの。
例: "full_name":"San Francisco, CA" |
| id | String |
このplaceを表すID。これは数字ではなく文字列で表されるので注意してください。
例: "id":"7238f93a3e899af6" |
| name | String |
place名を人にも読める形で短縮表記したもの。
例: "name":"Paris" |
| place_type | String |
このplaceを表す位置タイプ。
例: "place_type":"city" |
| url | String |
このplaceの追加メタデータがあるアドレスを表すURL。
例: "url":"https://api.twitter.com/1.1/geo/id/7238f93a3e899af6.json" |
| フィールド | 型 | 説明 |
|---|---|---|
| coordinates | Float型の三次配列 |
A series of longitude and latitude points, defining a box which will contain the Place entity this bounding box is related to.
各座標は [経度, 緯度] 形式の配列になっています。 各座標は領域範囲ごとにグループ化されています。
領域範囲の配列は、polygon表記との互換性を保つためにさらにもう一段階上の配列に格納されます。
例: "coordinates":[ [ [2.2241006,48.8155414], [2.4699099,48.8155414], [2.4699099,48.9021461], [2.2241006,48.9021461] ] ] |
| type | String |
coordinates プロパティでエンコードされているデータのタイプ。領域範囲の場合、これは “Polygon” になります。
例: "type":"Polygon" |
Place 属性は、 placesについてのメタデータです。いくつのかの場合を除き、この属性は「キーと値」という形の文字列を組み合わせたものになります。
以下は良く使われる place 属性です。場合によっては取得データ内に含まれないこともあります。Twitter のplaces データベース内でplaceが作成されたタイミングで、これらの属性は設定されます。
| キー | 説明 |
|---|---|
| street_address | |
| locality | このplaceが属する都市 |
| region | このplaceが属する行政範囲 |
| iso3 | 国コード |
| postal_code | このplaceを表すのに適した local 形式 |
| phone | 長距離コードを含む、このplaceを表すのに適した local 形式 |
| twitter スクリーンネームから@を除いた値 | |
| url | placeの公式/非公式 URL |
| app:id | アプリケーションplace データベースにおけるplace を表したID、もしくはそのIDをコンマ区切りで複数まとめた一覧。 |
キーの長さが140文字を超えることはありません。値はユニコード文字列で最大2000文字です。
以下の例では、API v1.1を実行する際にOAuth 認証が必要です。
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"
}