swarm API 備忘録（実用例）

swarm API (Foursquare API) を利用して，

周辺のスポットを検索
チェックイン
チェックインをシェア

ができたので，その概要について書きます。

とりあえずAPIを使えるようにするのを昨日やりましたが

o-treetree.hatenablog.com

今回はその発展形です。相変わらず，curlで，パラメータをクエリでくっつけてやってます。

周辺を検索
リクエストパラメータqueryについて
チェックイン
チェックインのシェア
参考

変数について

CLIENT_ID : 先の記事で取得方法を説明したID。各自のものに書き換える
CLIENT_SECRET : 同じく，SECRET。
ACCESS_TOKEN : ユーザー認証で得られたアクセストークン。認証したユーザーに固有。

周辺を検索

先の記事中の例ではエンドポイントvenues/explore(Get Venue Recommendations )で周辺のスポットを検索していました。これで取得できるvenueのリストが，swarmアプリの上で見られるものと違うなぁと思っていたのですが，FAQページにこんなことが書いてありました。

Could you elaborate more on venues/explore vs. venues/search?

Both venues/explore and venues/search allow you to find venues in an area, but their methodologies are slightly different. venues/explore is better at answering the question “what are some popular coffee shops in this area?” whereas venues/search is better at “where is the nearest Joe’s Coffee?” or “where am I right now?”. When using venues/search, you should pay attention to what the intent parameter does and what values you should provide in order to get your desired results.

FAQ - API Support

要するに

venues/exploreは近くのおすすめスポットを教えてくれる
venues/searchは近くのスポットを教えてくれる

ということで，venues/search(Search for Venues )を使った方が良さそうです。

仕様

メソッド : GET
URL : https://api.foursquare.com/v2/venues/search
認証 : 認証なしだと，その場に何人いるか表示されましたが，認証を入れるとそれが出ませんでした。後述。

パラメータ

ぱっと使うために必要なもの。

名前	例	説明
`ll`	35.6586,139.7454	緯度，経度
`intent`	`checkin, browse`等	探索方法。指定なければ`checkin`
`radius`	250	半径
`query`	ここ参照	検索文字列
`limit`	5	表示する数

リクエスト

東京タワー(35.6586,139.7454)周辺のスポットを認証なしで5つ検索

curl "https://api.foursquare.com/v2/venues/search\
?client_id=CLIENT_ID\
&client_secret=CLIENT_SECRET\
&v=20180323\
&ll=35.6586,139.7454\
&limit=5\
&locale=ja"

memo

GETのときは curl "ホニャララ"で可能

バックスラッシュをつけると途中で改行可能。

言語指定

最後につけたパラメータlocaleで，レスポンスの言語の指定ができる。つけなかったら，リクエストをブラウザのURL枠に入れればどこかで処理してくれるっぽいけどターミナルだと英語で返ってきてしまう。ターミナルで日本語を得るにはlocale=jaをつける。

locale=jaを指定すれば以下のようにレスポンスが日本語で来る（以下の，["respons"]["venues"]["hereNow"]["summary"]等が英->日変換される。venue名や地名等はどちらも日本語）

レスポンス

▼ 長いので折り畳み


{
    "meta": {
        "code": 200,
        "requestId": 一応隠す
    },
    "response": {
        "venues": [
            {
                "id": "4b56a5e8f964a5208e1728e3",
                "name": "東京タワー",
                "contact": {},
                "location": {
                    "address": "芝公園4-2-8",
                    "lat": 35.65857854321072,
                    "lng": 139.74544197320938,
                    "labeledLatLngs": [
                        {
                            "label": "display",
                            "lat": 35.65857854321072,
                            "lng": 139.74544197320938
                        }
                    ],
                    "distance": 4,
                    "postalCode": "105-0011",
                    "cc": "JP",
                    "neighborhood": "芝公園",
                    "city": "東京",
                    "state": "東京都",
                    "country": "日本",
                    "formattedAddress": [
                        "芝公園4-2-8",
                        "港区, 東京都",
                        "105-0011",
                        "日本"
                    ]
                },
                "categories": [
                    {
                        "id": "4bf58dd8d48988d12d941735",
                        "name": "記念碑 / ランドマーク",
                        "pluralName": "記念碑 / ランドマーク",
                        "shortName": "ランドマーク",
                        "icon": {
                            "prefix": "https://ss3.4sqi.net/img/categories_v2/building/government_monument_",
                            "suffix": ".png"
                        },
                        "primary": true
                    }
                ],
                "verified": false,
                "stats": {
                    "tipCount": 0,
                    "usersCount": 0,
                    "checkinsCount": 0,
                    "visitsCount": 0
                },
                "beenHere": {
                    "count": 0,
                    "lastCheckinExpiredAt": 0,
                    "marked": false,
                    "unconfirmedCount": 0
                },
                "hereNow": {
                    "count": 3,
                    "summary": "3 人の人たちがここにいます",
                    "groups": [
                        {
                            "type": "others",
                            "name": "ここに他の人たちがいます",
                            "count": 3,
                            "items": []
                        }
                    ]
                },
                "referralId": "v-1567342805",
                "venueChains": [],
                "hasPerk": false
            },
            {
                "id": "4be0feaac1732d7f67115b9a",
                "name": "メインデッキ",
                "contact": {},
                "location": {
                    "address": "芝公園4-2-8",
                    "crossStreet": "東京タワー 150m",
                    "lat": 35.65858024547952,
                    "lng": 139.74549340811524,

        …………

        同じような内容なので省略

        …………

        ],
        "confident": false
    }
}

レスポンス解説

パス(`["respons"]["venues"]`以下)	例	解説
`[0]["id"]`	4b56a5e8f964a5208e1728e3	venueの固有id
`[0]["name"]`	東京タワー	venueの名前
`[0]["location"]["address"]`	芝公園4-2-8	住所
`[0]["location"]["hereNow"]["count"]`	3	現在(いつ？)チェックインしている人の数

`[1]["name"]`	メインデッキ
`[1]["location"]["crossStreet"]`	東京タワー 150m	venueを内包する場所の名前(?)

認証ありで検索すると，["hereNow"]その他数個のパラメータが無い。詳しくは分からん

リクエストパラメータ`query`について

検索文字列だけど，半角英数以外のものを入れる時は置き換え（URLエンコード）しなければいけない。下記のチェックイン時のコメントshoutに文字列を入れる時も同様の変換が必要。

文字列	置き換え
[空白]	+ あるいは %20
[ASCII文字]	%{ASCIIcode16進}
[ひらがなとか]	ここで変換
タワー	%E3%82%BF%E3%83%AF%E3%83%BC

東京タワー(35.6586,139.7454)の周り100mで名前に「タワー」を含むvenueを5つ探すリクエスト

どうも，query指定で探すには，intent=browseとしてradiusを追加するのが良いようだ。

curl "https://api.foursquare.com/v2/venues/search\
?client_id=CLIENT_ID\
&client_secret=CLIENT_SECRET\
&v=20180323\
&ll=35.6586,139.7454\
&radius=100\
&intent=browse\
&limit=5\
&locale=ja\
&query=%E3%82%BF%E3%83%AF%E3%83%BC"

チェックイン

venues/searchで探したスポットから，好きなものを選んだら（ここの実装は各自）checkins/add(Create a Check-in )を利用してチェックインできます。

仕様

メソッド : POST
URL : https://api.foursquare.com/v2/checkins/add
認証 : ユーザー認証必須

パラメータ

選んだスポット（ここでは東京タワー）にチェックインするだけなら

名前	例	説明
`viewId`	4b56a5e8f964a5208e1728e3	先ほど取得済み
`shout`	This+is+a+test+checkin%21	URLエンコードについてここ参照
`broadcast`	`public, private`等	指定なければ`public`

リクエスト

東京タワーに，「this is second TEST checkin!」と（いろいろ試していた痕跡をコピペしたら"second TEST"のままだった…………）コメントを添えてチェックイン

curl -X POST "https://api.foursquare.com/v2/checkins/add\
?oauth_token=ACCESS_TOKEN\
&v=20190830\
&locale=ja\
&venueId=4b56a5e8f964a5208e1728e3\
&shout=this%20is%20second%20TEST%20checkin%21"

レスポンス

▼ 長いので折り畳み


{
    "meta": {
        "code": 200,
        "requestId": "一応隠す"
    },
    "notifications": [
        {
            "type": "notificationTray",
            "item": {
                "unreadCount": 0
            }
        }
    ],
    "response": {
        "checkin": {
            "id": "5d6bd1c1290dda000838b277",
            "createdAt": 1567347137,
            "type": "checkin",
            "entities": [],
            "shout": "this is second TEST checkin!",
            "timeZoneOffset": 540,
            "editableUntil": 1567433537000,
            "user": {
                "id": "550622851",
                "firstName": "ohayashi",
                "gender": "male",
                "relationship": "self",
                "photo": {
                    "prefix": "https://fastly.4sqi.net/img/user/",
                    "suffix": "/blank_boy.png",
                    "default": true
                },
                "coinBalance": 171
            },
            "venue": {
                "id": "4b56a5e8f964a5208e1728e3",
                "name": "東京タワー",
                "location": {
                    "address": "芝公園4-2-8",
                    "lat": 35.65857854321072,
                    "lng": 139.74544197320938,
                    "labeledLatLngs": [
                        {
                            "label": "display",
                            "lat": 35.65857854321072,
                            "lng": 139.74544197320938
                        }
                    ],
                    "postalCode": "105-0011",
                    "cc": "JP",
                    "neighborhood": "芝公園",
                    "city": "東京",
                    "state": "東京都",
                    "country": "日本",
                    "formattedAddress": [
                        "芝公園4-2-8",
                        "港区, 東京都",
                        "105-0011"
                    ]
                },
                "categories": [
                    {
                        "id": "4bf58dd8d48988d12d941735",
                        "name": "記念碑 / ランドマーク",
                        "pluralName": "記念碑 / ランドマーク",
                        "shortName": "ランドマーク",
                        "icon": {
                            "prefix": "https://ss3.4sqi.net/img/categories_v2/building/government_monument_",
                            "suffix": ".png"
                        },
                        "primary": true
                    }
                ],
                "reasons": {
                    "count": 1,
                    "items": [
                        {
                            "summary": "ここにいる人",
                            "type": "general",
                            "reasonName": "hereNowReason",
                            "target": {
                                "type": "navigation",
                                "object": {
                                    "id": "5d6bd1c2290dda000838b386",
                                    "type": "checkinDetail",
                                    "target": {
                                        "type": "path",
                                        "url": "/checkins/5d6bd1c1290dda000838b277"
                                    },
                                    "ignorable": false
                                }
                            }
                        }
                    ]
                }
            },
            "source": {
                "name": "ohatest",
                "url": "https://o-treetree.hatenablog.com"
            },
            "photos": {
                "count": 0,
                "items": []
            },
            "posts": {
                "count": 0,
                "textCount": 0
            },
            "checkinShortUrl": "https://www.swarmapp.com/user/550622851/checkin/5d6bd1c1290dda000838b277?s=3vOe6tbiwcAgZLA_ial3X1jZY3k",
            "likes": {
                "count": 0,
                "groups": []
            },
            "like": false,
            "comments": {
                "count": 0,
                "items": []
            },
            "isMayor": false,
            "score": {
                "total": 14,
                "scores": [
                    {
                        "icon": "https://ss1.4sqi.net/img/points/coin_icon_magnify.png",
                        "message": "東京タワー で初のチェックインです！",
                        "points": 5
                    },
                    {
                        "icon": "https://ss1.4sqi.net/img/points/coin_icon_magnify.png",
                        "message": "初めての 記念碑 / ランドマーク です！",
                        "points": 5
                    },
                    {
                        "icon": "https://ss1.4sqi.net/img/points/coin_icon_plane.png",
                        "message": "最後のチェックイン以来の 549マイル",
                        "points": 3
                    },
                    {
                        "icon": "https://ss1.4sqi.net/img/points/coin_icon_streak.png",
                        "message": "東京タワーではいろいろなことが起こっています! もっとたくさんのスポットにチェックインしてコインを獲得しましょう。",
                        "points": 1
                    }
                ]
            }
        },
        "notifications": [
            {
                "type": "message",
                "item": {
                    "message": "あなたがここにチェックインするのは初めて",
                    "entities": []
                },
                "alert": false
            },
            {
                "type": "insights",
                "item": {
                    "insights": {
                        "count": 4,
                        "items": [
                            {
                                "type": "pointsReward",
                                "image": "https://ss1.4sqi.net/img/points/coin_icon_magnify_120.png",
                                "title": "東京タワー で初のチェックインです！",
                                "points": {
                                    "image": {
                                        "prefix": "https://ss1.4sqi.net/img/points/coin_icon_magnify_",
                                        "sizes": [
                                            80,
                                            120
                                        ],
                                        "name": ".png",
                                        "key": "magnify"
                                    },
                                    "message": "東京タワー で初のチェックインです！",
                                    "points": 5
                                }
                            },
                            {
                                "type": "pointsReward",
                                "image": "https://ss1.4sqi.net/img/points/coin_icon_magnify_120.png",
                                "title": "初めての 記念碑 / ランドマーク です！",
                                "points": {
                                    "image": {
                                        "prefix": "https://ss1.4sqi.net/img/points/coin_icon_magnify_",
                                        "sizes": [
                                            80,
                                            120
                                        ],
                                        "name": ".png",
                                        "key": "magnify"
                                    },
                                    "message": "初めての 記念碑 / ランドマーク です！",
                                    "points": 5
                                }
                            },
                            {
                                "type": "pointsReward",
                                "image": "https://ss1.4sqi.net/img/points/coin_icon_plane_120.png",
                                "title": "最後のチェックイン以来の 549マイル",
                                "points": {
                                    "image": {
                                        "prefix": "https://ss1.4sqi.net/img/points/coin_icon_plane_",
                                        "sizes": [
                                            80,
                                            120
                                        ],
                                        "name": ".png",
                                        "key": "plane"
                                    },
                                    "message": "最後のチェックイン以来の 549マイル",
                                    "points": 3
                                }
                            },
                            {
                                "type": "pointsReward",
                                "image": "https://ss1.4sqi.net/img/points/coin_icon_streak_120.png",
                                "title": "東京タワーではいろいろなことが起こっています! もっとたくさんのスポットにチェックインしてコインを獲得しましょう。",
                                "points": {
                                    "image": {
                                        "prefix": "https://ss1.4sqi.net/img/points/coin_icon_streak_",
                                        "sizes": [
                                            80,
                                            120
                                        ],
                                        "name": ".png",
                                        "key": "streak"
                                    },
                                    "message": "東京タワーではいろいろなことが起こっています! もっとたくさんのスポットにチェックインしてコインを獲得しましょう。",
                                    "points": 1
                                }
                            }
                        ]
                    }
                },
                "alert": true
            }
        ],
        "notificationsOrder": [
            "special",
            "score",
            "leaderboard",
            "replies"
        ]
    }
}

レスポンス解説

パス（["response"]["checkin"]以下）	例	解説
["id"]	5d6bd1c1290dda000838b277	checkinのID
["createdAt"]	1567347137	UNIXタイムスタンプ（2019/09/01 23:12:17 Tokyo）
["shout"]	this is second TEST checkin!	コメント
["user"]["id"]	550622851	僕のswarmアカウントのユーザーID
["user"]["firstName"]	ohayashi	同，名前
["venue"]["……"]		チェックインしたvenueの各情報

チェックインのシェア

チェックインをシェアするには， ["response"]["checkin"]["checkinShortUrl"]を使用します。上記の東京タワーへのチェックインでは https://www.swarmapp.com/user/550622851/checkin/5d6bd1c1290dda000838b277?s=3vOe6tbiwcAgZLA_ial3X1jZY3kとなっている。

こんな感じ

これでswarmアプリもどきを作れるようになりました！！！

日付ギリギリ！！！おしまい！！！！！