Nearby Search(従来版)では、指定された範囲内で場所を検索できます。キーワードを指定したり、検索する場所の種類を指定したりして、検索リクエストを絞り込むことができます。
Nearby Search(従来版)リクエスト
Nearby Search(従来版)リクエストは、次の形式の HTTP URL です。
https://maps.googleapis.com/maps/api/place/nearbysearch/output?parameters
ここで、output には次のいずれかの値を指定できます。
json(推奨)は、JavaScript Object Notation(JSON)での出力を示します。xmlは、XML としての出力を示します。
Nearby Search(従来版)リクエストを開始するには、特定のパラメータが必要です。URL の標準規則と同様に、すべてのパラメータはアンパサンド(&)文字を使用して区切ります。
必須パラメータ
-
ロケーション
場所情報を取得する中心点。これは
latitude,longitudeとして指定する必要があります。 -
半径
場所の結果を返す距離(メートル単位)を定義します。
locationパラメータとradiusパラメータを渡すことで、バイアスを設定し、指定した円の範囲内の結果を優先します。これによって、プレイス サービスが指定した範囲内を優先するように検索結果を絞り込むことができますが、指定した範囲外の結果が返されることもあります。半径は、検索の種類やその他のパラメータに応じて、自動的に最大値に制限されます。
- 予測入力: 50,000 メートル
-
Nearby Search:
keywordまたはnameの場合: 50,000 メートル-
keywordまたはnameなし-
最大 50,000 m。
rankbyパラメータとは無関係に、エリアの密度に基づいて動的に調整されます。 -
rankby=distanceを使用する場合、radius パラメータは受け入れられず、INVALID_REQUESTが返されます。
-
最大 50,000 m。
- Query Autocomplete: 50,000 メートル
- テキスト検索: 50,000 メートル
オプション パラメータ
-
キーワード
検索するテキスト文字列(「レストラン」、「123 番通り」など)です。地名、住所、施設のカテゴリのいずれかを入力する必要があります。他の種類のテキストを入力した場合、有効な結果が返されず、エラーが発生する場合があります。Google プレイス サービスはこの文字列と一致する候補を、関連性の高い順に並べて結果として返します。
このパラメータを使用して位置情報を明示的に指定すると、location、radius、rankby の各パラメータと競合し、予期しない結果が生じる可能性があります。
このパラメータを省略すると、business_status が CLOSED_TEMPORARILY または CLOSED_PERMANENTLY の場所は返されません。
-
言語
結果を返す言語。
- サポートされている言語の一覧をご覧ください。サポート対象の言語は頻繁に更新されるため、このリストで網羅されていない場合があります。
-
languageが指定されていない場合、API はAccept-Languageヘッダーで指定された優先言語を使用しようとします。 - API は、ユーザーと現地の人の両方が読み取れる番地を提供するように最善を尽くします。この目標を達成するため、住所は現地語で返されます。必要に応じて、ユーザーが読み取れる文字に変換され、優先言語が考慮されます。その他の住所はすべて、優先言語で返されます。住所コンポーネントはすべて同じ言語で返されます。この言語は、最初のコンポーネントから選択されます。
- 優先言語で名前が利用できない場合、API は最も近い一致を使用します。
- 優先言語は、API が返す結果のセットと、それらが返される順序にわずかに影響します。ジオコーダは、言語に応じて略語を異なる方法で解釈します。たとえば、道路タイプの略語や、ある言語では有効でも別の言語では有効でない類義語などです。たとえば、utca と tér は、ハンガリー語で「通り」の同義語です。
-
maxprice
指定した範囲内の場所に結果を制限します。有効な値の範囲は 0(最も安い)〜4(最も高い)です。特定の値で示される正確な金額は、地域によって異なります。
-
minprice
指定した範囲内の場所に結果を制限します。有効な値の範囲は 0(最も安い)〜4(最も高い)です。特定の値で示される正確な金額は、地域によって異なります。
-
name
keywordと同じです。このフィールドの値は、keywordフィールドの値と組み合わされて、同じ検索文字列の一部として渡されます。 -
opennow
クエリが送信された時点で営業している場所のみを返します。クエリにこのパラメータを指定した場合、Google プレイスのデータベースに営業時間が登録されていない場所は返されません。
-
pagetoken
以前に実行した検索から最大 20 件の結果を返します。
pagetokenパラメータを設定すると、以前に使用したパラメータと同じパラメータで検索が実行されます。pagetoken以外のパラメータはすべて無視されます。 -
rankby
結果を一覧表示する順序を指定します。次の値があります。
-
prominence(デフォルト)。このオプションを指定した場合は、場所の重要度で検索結果が並べられます。設定された半径内の重要度の高い場所が、一致するものの重要度が低い付近の場所より優先されます。重要度は、Google のインデックスでの場所のランキングや、グローバルな人気度などの要因によって決まります。目立ち度を指定する場合は、radiusパラメータが必要です。 -
distance。このオプションを指定した場合は、指定した場所からの距離に応じて検索結果が昇順で並べられます。distanceを指定する場合は、keyword、name、typeのうち 1 つ以上が必要です。radiusは指定できません。
-
-
type
指定したタイプに一致する場所のみに結果を制限します。指定できるタイプは 1 つだけです。複数のタイプを指定すると、API は最初のエントリの後に指定したタイプをすべて無視します。
-
type=hospital|pharmacy|doctorをtype=hospitalに変更します。 type=hospital,pharmacy,doctorは完全に無視されます。
サポートされているタイプのリストをご覧ください。
注:keywordとtypeを同じ値 (keyword=cafe&type=cafeまたはkeyword=parking&type=parking) で加算すると、ZERO_RESULTSになります。 -
Nearby Search(従来版)の例
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522%2C151.1957362&radius=1500&type=restaurant&keyword=cruise&key=YOUR_API_KEY'HTTP
https://maps.googleapis.com/maps/api/place/nearbysearch/json ?keyword=cruise &location=-33.8670522%2C151.1957362 &radius=1500 &type=restaurant &key=YOUR_API_KEY
注: この例では、アプリケーションでリクエストが機能するように、key を独自の API キーに置き換える必要があります。
Nearby Search(従来版)のレスポンス
次の例は、Nearby Search(従来版)のレスポンスを示しています。
JSON
{ "html_attributions": [], "results": [ { "business_status": "OPERATIONAL", "geometry": { "location": { "lat": -33.8587323, "lng": 151.2100055 }, "viewport": { "northeast": { "lat": -33.85739847010727, "lng": 151.2112436298927 }, "southwest": { "lat": -33.86009812989271, "lng": 151.2085439701072 }, }, }, "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/bar-71.png", "icon_background_color": "#FF9E67", "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/bar_pinlet", "name": "Cruise Bar", "opening_hours": { "open_now": false }, "photos": [ { "height": 608, "html_attributions": [ 'A Google User', ], "photo_reference": "Aap_uECvJIZuXT-uLDYm4DPbrV7gXVPeplbTWUgcOJ6rnfc4bUYCEAwPU_AmXGIaj0PDhWPbmrjQC8hhuXRJQjnA1-iREGEn7I0ZneHg5OP1mDT7lYVpa1hUPoz7cn8iCGBN9MynjOPSUe-UooRrFw2XEXOLgRJ-uKr6tGQUp77CWVocpcoG", "width": 1080, }, ], "place_id": "ChIJi6C1MxquEmsR9-c-3O48ykI", "plus_code": { "compound_code": "46R6+G2 The Rocks, New South Wales", "global_code": "4RRH46R6+G2", }, "price_level": 2, "rating": 4, "reference": "ChIJi6C1MxquEmsR9-c-3O48ykI", "scope": "GOOGLE", "types": ["bar", "restaurant", "food", "point_of_interest", "establishment"], "user_ratings_total": 1269, "vicinity": "Level 1, 2 and 3, Overseas Passenger Terminal, Circular Quay W, The Rocks", }, { "business_status": "OPERATIONAL", "geometry": { "location": { "lat": -33.8675219, "lng": 151.2016502 }, "viewport": { "northeast": { "lat": -33.86614532010728, "lng": 151.2031259298927 }, "southwest": { "lat": -33.86884497989272, "lng": 151.2004262701072 }, }, }, "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/generic_business-71.png", "icon_background_color": "#7B9EB0", "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet", "name": "Sydney Harbour Dinner Cruises", "opening_hours": { "open_now": true }, "photos": [ { "height": 835, "html_attributions": [ 'A Google User', ], "photo_reference": "Aap_uEBVsYnNcrpRixtrlHBztigZh70CwYkNWZzQnqJ39SjeBo_wvgKf-kXc6tgaMLBdQrRKmxmSKjOezoZrv-sHKVbTX0OI48HBqYYVnQiZQ-WGeuQDsLEPwX7LaVPa68nUAxX114Zpqt7bryoO9wL4qXdgEnopbOp5WWLALhKEHoIEH7f7", "width": 1200, }, ], "place_id": "ChIJM1mOVTS6EmsRKaDzrTsgids", "plus_code": { "compound_code": "46J2+XM Sydney, New South Wales", "global_code": "4RRH46J2+XM", }, "rating": 4.8, "reference": "ChIJM1mOVTS6EmsRKaDzrTsgids", "scope": "GOOGLE", "types": [ "tourist_attraction", "travel_agency", "restaurant", "food", "point_of_interest", "establishment", ], "user_ratings_total": 9, "vicinity": "32 The Promenade, Sydney", }, // ... ], "status": "OK", }
XML
<?xml version="1.0" encoding="UTF-8"?> <PlaceSearchResponse> <status>OK</status> <result> <name>Cruise Bar</name> <vicinity>Level 1, 2 and 3, Overseas Passenger Terminal, Circular Quay W, The Rocks</vicinity> <type>bar</type> <type>restaurant</type> <type>food</type> <type>point_of_interest</type> <type>establishment</type> <geometry> <location> <lat>-33.8587323</lat> <lng>151.2100055</lng> </location> <viewport> <southwest> <lat>-33.8600981</lat> <lng>151.2085440</lng> </southwest> <northeast> <lat>-33.8573985</lat> <lng>151.2112436</lng> </northeast> </viewport> </geometry> <rating>4.0</rating> <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/bar-71.png</icon> <reference>ChIJi6C1MxquEmsR9-c-3O48ykI</reference> <opening_hours> <open_now>false</open_now> </opening_hours> <photo> <photo_reference>Aap_uEALIq4sgBHhIYWWapOH2NV1T2I7YdOiLzEH7z-483I764cId1sZkbzSq-hVYTk1PQeaHuZzlRfA7-ilwJ3QWon4b37ePd-PBwZbOwFZHxhYs0Cs7jRSgMHWfOzGivp6ZFG4iupyz50qS5pBZT1WbA2ufacTq_U21TtgffQD31wKRPQk</photo_reference> <width>1080</width> <height>608</height> <html_attribution><a href="https://maps.google.com/maps/contrib/112582655193348962755">A Google User</a></html_attribution> </photo> <price_level>2</price_level> <user_ratings_total>1269</user_ratings_total> <place_id>ChIJi6C1MxquEmsR9-c-3O48ykI</place_id> <scope>GOOGLE</scope> <plus_code> <global_code>4RRH46R6+G2</global_code> <compound_code>46R6+G2 The Rocks, New South Wales</compound_code> </plus_code> <icon_background_color>#FF9E67</icon_background_color> <business_status>OPERATIONAL</business_status> <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/bar_pinlet</icon_mask_base_uri> </result> <result> <name>Sydney Harbour Dinner Cruises</name> <vicinity>32 The Promenade, Sydney</vicinity> <type>tourist_attraction</type> <type>restaurant</type> <type>food</type> <type>travel_agency</type> <type>point_of_interest</type> <type>establishment</type> <geometry> <location> <lat>-33.8675219</lat> <lng>151.2016502</lng> </location> <viewport> <southwest> <lat>-33.8688450</lat> <lng>151.2004263</lng> </southwest> <northeast> <lat>-33.8661453</lat> <lng>151.2031259</lng> </northeast> </viewport> </geometry> <rating>4.8</rating> <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/generic_business-71.png</icon> <reference>ChIJM1mOVTS6EmsRKaDzrTsgids</reference> <opening_hours> <open_now>true</open_now> </opening_hours> <photo> <photo_reference>Aap_uEB5jH7GXdcozv1Y5HX18syo4f128S58NVUnqBbLJMpWbC39K49wp-wzsLOsUT8QKDaag6ISFL8hl1vVuig4jkc5fMMkWKiqw5PY-ebcWZ5tI3gEXEYGGoG_mDAulaMLudUpSwgBx2_RLnA0SSiugqqQUTYlkGyCZSe8HSyngVczy6XN</photo_reference> <width>1200</width> <height>835</height> <html_attribution><a href="https://maps.google.com/maps/contrib/109764923610545394994">A Google User</a></html_attribution> </photo> <user_ratings_total>9</user_ratings_total> <place_id>ChIJM1mOVTS6EmsRKaDzrTsgids</place_id> <scope>GOOGLE</scope> <plus_code> <global_code>4RRH46J2+XM</global_code> <compound_code>46J2+XM Sydney, New South Wales</compound_code> </plus_code> <icon_background_color>#7B9EB0</icon_background_color> <business_status>OPERATIONAL</business_status> <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet</icon_mask_base_uri> </result> <!-- ... --> </PlaceSearchResponse>
PlacesNearbySearchResponse
| フィールド | 必須 | タイプ | 説明 |
|---|---|---|---|
|
required | Array<string> |
このリスティングに関する一連の帰属情報が含まれる場合があります。この情報はユーザーに表示する必要があります(一部のリスティングには帰属情報がない場合があります)。 |
|
required | Array<Place> |
場所の配列が含まれます。
Place Search リクエストでは、Place Details リクエストで返されるフィールドのサブセットが返されます。目的のフィールドが Place Search で返されない場合は、Place Search を使用して
place_id を取得してから、そのプレイス ID を使用して Place Details リクエストを実行します。詳細については、Place をご覧ください。 |
|
required | PlacesSearchStatus |
リクエストのステータスが格納されます。リクエストが失敗した原因を追跡できるようにデバッグ情報が格納される場合もあります。 詳細については、PlacesSearchStatus をご覧ください。 |
|
省略可 | 文字列 |
サービスが |
|
省略可 | Array<string> |
サービスがリクエスト仕様に関する追加情報を返す場合、レスポンス オブジェクト内に追加の |
|
省略可 | 文字列 |
最大 20 件の追加の結果を返すために使用できるトークンが含まれています。表示する追加の結果がない場合、next_page_token は返されません。返される結果の最大数は 60 です。next_page_token が発行されてから有効になるまでには、短い遅延があります。 |
PlacesSearchStatus
サービスから返されるステータス コード。
OKは、API リクエストが成功したことを示します。-
ZERO_RESULTSは、検索は成功したものの結果が返されなかったことを示します。これは、遠隔地のlatlngが検索に渡された場合に発生することがあります。 -
INVALID_REQUESTは、API リクエストの形式が正しくないことを示します。通常は、必須のクエリ パラメータ(locationまたはradius)が不足していることが原因です。 -
OVER_QUERY_LIMIT。次のいずれかを示します。- QPS の上限を超えている。
- アカウントで課金が有効になっていない。
- 毎月 200 ドル分のクレジット、またはご自身で設定した使用量の上限を超えている。
- 設定したお支払い方法が無効になっている(クレジット カードの期限切れなど)
-
REQUEST_DENIEDは、リクエストが拒否されたことを示します。一般的には、次の理由が考えられます。- リクエストに API キーがありません。
keyパラメータが無効です。
UNKNOWN_ERRORは、不明なエラーが発生したことを示します。
場所
Place Search のレスポンスでは、Place フィールドの次のサブセットが返されます。すべての属性がすべての場所タイプで使用できるわけではありません。Place Search で返されないフィールド(address_components、formatted_phone_number、reviews、website など)を取得するには、返された place_id を Place Details(従来版)リクエストで渡します。エンドポイント全体のフィールドの可用性と料金階層については、プレイスデータ フィールド(レガシー)をご覧ください。
| フィールド | タイプ | 説明 |
|---|---|---|
business_status |
string |
その場所の営業状況を示します(場所がお店やサービスの場合)。OPERATIONAL、CLOSED_TEMPORARILY、CLOSED_PERMANENTLY のいずれかです。ステータス データが存在しない場合は省略されます。
|
formatted_address |
string |
この場所の人が読める形式の住所。テキスト検索(従来版)と Find Place(従来版)によって返されます。フォーマット済み住所は、プログラムで解析しないでください。代わりに、Place Details(従来版)で address_components をリクエストしてください。 |
geometry |
Geometry
|
lat 座標と lng 座標を持つジオコーディングされた location と、northeast 境界と southwest 境界を持つ優先 viewport が含まれます。
|
icon |
string |
この結果を地図上に表示する際に使用できる、推奨アイコンの URL。 |
icon_background_color
|
string |
場所のカテゴリのデフォルトの 16 進数色コード。 |
icon_mask_base_uri |
string |
推奨アイコンのベース URL。SVG または PNG のファイル形式の拡張子は含まれません。 |
name |
string |
返された結果の人が読める形式の名前。establishment の結果の場合、この値は通常、正規化されたビジネス名です。 |
opening_hours |
PlaceOpeningHours
|
営業時間に関する情報。Place Search エンドポイントは、open_now ブール値サブフィールドのみを返します。periods と weekday_text については、Place Details(従来版)で opening_hours をリクエストします。 |
permanently_closed |
boolean |
非推奨: business_status を使用してお店やサービスの営業状況を確認してください。
|
photos |
Array<PlacePhoto>
|
PlacePhoto オブジェクトの配列。各オブジェクトには、photo_reference、height、width、html_attributions が含まれます。使用方法の詳細については、Place Photos(従来版)をご覧ください。 |
place_id |
string |
場所を一意に識別するテキスト表記の ID。この ID を Place Details(従来版)リクエストの place_id パラメータに渡します。プレイス ID の概要をご覧ください。 |
plus_code |
PlusCode
|
緯度と経度の座標から派生したエンコードされた場所の参照。global_code とオプションの compound_code が含まれます。 |
price_level |
integer |
場所の価格レベル。0 から 4 の範囲で、最も安いものから最も高いものまでを表します。price_level をご覧ください。 |
rating |
number |
ユーザーのクチコミの集計に基づく場所の評価(1.0~5.0)。 |
reference |
string |
非推奨: 代わりに place_id を使用してください。 |
scope |
string |
非推奨: place_id のスコープを示します。これは常に GOOGLE です。Nearby Search(従来版)によって返されます。 |
types |
Array<string> |
指定された結果を記述する特徴タイプの配列。プレイスタイプ(従来版)をご覧ください。 |
user_ratings_total |
integer |
この場所の評価の合計数(レビュー テキストの有無にかかわらず)。 |
vicinity |
string |
場所の簡単な住所です。番地や市町村などが含まれ、州、都道府県、郵便番号、国などは含まれません。Nearby Search(従来版)によって返されます。 |
追加の結果へのアクセス
デフォルトでは、各レスポンスは 1 つのクエリに対して最大 20 件の establishment の結果を返します。ただし、各検索では、3 ページに分けて最大 60 件の結果を返すことができます。検索結果が 20 件を超える場合、検索レスポンスには追加の値 next_page_token が含まれます。next_page_token の値を新しいリクエストの pagetoken パラメータに渡して、次の結果セットを表示します。
next_page_tokenが null であるか、返されない場合、それ以上の結果はありません。- 同じ
next_page_tokenを使用してリクエストを再試行すると、結果の次のページが返されます。 pagetokenを設定すると、他のパラメータは無視されます。- 元のクエリに続いて、新しいページを 2 回までリクエストできます。
next_page_tokenを使用するリクエストを含む各リクエストは、使用量上限に対して 1 件のリクエストとしてカウントされ、個別に課金されます。next_page_tokenが発行されてから有効になるまでには数秒の遅延があります。次のページが利用可能になる前にリクエストすると、INVALID_REQUESTレスポンスが返されます。next_page_tokenを含むリクエストには常に課金されます。
たとえば、以下のクエリでは、オーストラリアのシドニーにあるダーリング ハーバーの近くのレストランを検索し、結果を距離順に並べ替えています。レスポンスに next_page_token プロパティが含まれていることがわかります。
{
"html_attributions" : [],
"next_page_token" : "CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q",
"results" : [...]
"status" : "OK"
}次の結果セットを表示するには、next_page_token の結果を pagetoken パラメータに渡して、新しいクエリを送信します。次に例を示します。
https://maps.googleapis.com/maps/api/place/nearbysearch/json?pagetoken=CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q&key=YOUR_API_KEY