Yahoo!ローカルサーチAPI

リクエストURL

XML
https://map.yahooapis.jp/search/local/V1/localSearch
JSONP
https://map.yahooapis.jp/search/local/V1/localSearch

目次


概要

Yahoo!ローカルサーチAPI(以下、ローカルサーチAPI)は、店舗、イベント、クチコミ情報などの地域・拠点情報(POI)を検索するためのAPIです。
検索対象は、全国の店舗を網羅した電話帳データおよび店舗オーナーなどからの投稿データです。

ローカルサーチAPIの主な機能は以下の通りです。

  • 地域・拠点情報の名称および業種をキーワードで検索できます。
  • 中心位置を指定して円範囲で絞り込めます。
  • 矩形範囲を指定して絞り込めます。

今すぐローカルサーチAPIを利用する

Client ID(アプリケーションID)の取得

ローカルサーチAPIを利用するためには、Client IDの取得が必要です。
ご利用ガイドの手順に従ってClient IDを取得してください。取得した時期によってはアプリケーションIDと表記される場合があります。

施設名称やカテゴリー名称などのキーワードで検索する

ローカルサーチAPIでは、リクエストパラメータ(query)に施設名称やカテゴリー名称などのキーワードを指定して、地域・拠点情報を検索できます。以下は「ラーメン」で指定した場合のサンプルリクエストです。
<あなたのClient ID(アプリケーションID)>には、ご自身のClient ID(アプリケーションID)を入れてください。

https://map.yahooapis.jp/search/local/V1/localSearch?appid=<あなたのClient ID(アプリケーションID)>&query=%E3%83%A9%E3%83%BC%E3%83%A1%E3%83%B3

施設の業種を指定して検索する

Yahoo! Open Local Platform(YOLP)の施設情報には、施設の種類を分類できるように、業種コードが登録されています。
リクエストパラメータの業種コード(gc)で対象を指定して、検索できます。
業種コードについては、YOLP業種コードをご覧ください。

以下は、0115001(業種名:カフェ)を指定した場合のサンプルリクエストです。

https://map.yahooapis.jp/search/local/V1/localSearch?appid=<あなたのClient ID(アプリケーションID)>&gc=0115001

都道府県、市区町村を指定して検索する

日本の地方公共団体につけられたコード番号である住所コード(日本工業規格(JIS) X 0401)を指定して、都道府県や市区町村ごとの情報を検索できます。都道府県は二桁、市区町村の場合は五桁で指定します。
リクエストパラメータの住所コード(ac)で対象を指定して、検索できます。

以下は、13103(住所コード:東京都港区)を指定した場合のサンプルリクエストです。

https://map.yahooapis.jp/search/local/V1/localSearch?appid=<あなたのClient ID(アプリケーションID)>&ac=13103

範囲を指定して検索する

中心の緯度経度と検索範囲を指定して、そのエリアの地域・拠点情報を検索できます。リクエストパラメータの緯度(lat)と経度(lon)で中心の緯度経度を指定し、リクエストパラメータ(dist)で半径の距離を指定します。またリクエストパラメータ(bbox)で、緯度経度を2点(左下と右上)指定して、矩形にエリアを指定できます。

以下のサンプルリクエストの1つ目は、緯度:lat=35.665662327484、経度:lon=139.73091159273(東京ミッドタウン周辺)で、半径3キロ以内:dist=3 を指定した場合です。
2つ目は、矩形エリア左下の緯度:35.663782、経度:139.727685、矩形エリア右上の緯度:35.669378、経度:139.734251(東京ミッドタウン周辺)を指定し、グルメの業種:gc=01で検索した場合です。

https://map.yahooapis.jp/search/local/V1/localSearch?appid=<あなたのClient ID(アプリケーションID)>&lat=35.665662327484&lon=139.73091159273&dist=3
https://map.yahooapis.jp/search/local/V1/localSearch?appid=<あなたのClient ID(アプリケーションID)>&gc=01&bbox=139.727685,35.663782,139.734251,35.669378

検索結果のソート順を指定する

検索結果のソート順を指定できます。範囲を指定して検索する場合は、中心点から近い順にソートするとより便利に検索結果を活用できます。以下はよく利用されるソート順です。
他にも多くのソート順がありますので、詳しくはリクエストパラメータをご覧ください。

  • hybrid - 距離、レーティング、クチコミ数など、さまざまなパラメータにより算出した適合度順
  • geo - 球面を考慮した、球面三角法による距離順

以下は、緯度:lat=35.665662327484、経度:lon=139.73091159273(東京ミッドタウン周辺)で、半径3キロ以内:dist=3 を指定し、球面三角法による距離順でソート:sort=geo した場合のサンプルリクエストです。

https://map.yahooapis.jp/search/local/V1/localSearch?appid=<あなたのClient ID(アプリケーションID)>&lat=35.665662327484&lon=139.73091159273&dist=3&sort=geo

リクエストパラメータ一覧

本APIは、GETメソッドのみサポートしています。「Web APIの使い方#GETとは」をご参照ください。

パラメータ 説明
appid
(必須)
string Client ID(アプリケーションID)。詳細はこちらをご覧ください。
device string APIの結果をモバイル端末に掲載する場合は「mobile」を指定してください。モバイル端末で掲載できない情報が非表示になります。
query string (UTF-8でエンコードされた)検索クエリーです。検索対象は、地域・拠点情報名称および業種(カセットによってはない場合があります)です。
cid string カセットIDです。カセットIDを用いて店舗データを検索できます。
コンマ「,」区切りで複数指定が可能です。
電話帳のcidは「d8a23e9e64a4c817227ab09858bc1330」です。
指定しない場合は、公開されているカセット全体が検索対象です。
uid string ユニークIDです。
コンマ「,」区切りで複数指定できます。
gid string 名寄せされた店舗IDです。
コンマ「,」区切りで複数指定が可能です。
id string カセット内で設定されたIDです。
コンマ「,」区切りで複数指定が可能です。
※カセットID(cid)と併せてご利用ください。
bid string ビルIDです。
コンマ「,」区切りで複数指定が可能です。
※ビルIDは変更になる場合があります。
group string gidを指定すると名寄せされた同一店舗をまとめて表示します。
※名寄せされた店舗の中でsortで指定した並び順の上位一件のみ表示されます。
※すべての店舗が必要な場合はdistinct=falseを指定してください。
distinct boolean group=gid時に重複レコードの表示を指定します。
デフォルトはtrueです。
名寄せされた店舗すべてが必要な場合にfalseをセットしてください。
※false の場合、リクエストパラメータのresultsは店舗のユニークの件数となるため、リクエストパラメータのresultsとレスポンスの<Count>の件数が異なります。
sort string
rating(デフォルト)
score
hybrid
review
kana
price
dist
geo
match
ソートの方法を指定します:
  • ratingは、星の数順にソートします。
  • scoreは、スコア順にソートします。
  • hybridは、口コミ件数や星の数などを重み付けした値の順にソートします。
  • reviewは、口コミ件数にソートします。
  • kanaは、アイウエオ順にソートします。
  • priceは、金額順にソートします。
  • distは、2点間の直線距離順にソートします。(geoより高速です)
  • geoは、球面三角法による2点間の距離順にソートします。
    ※距離順(dist/geo)を有効にするためには、lat,lonを指定してください。
  • matchは、適合度順にソートします。
デフォルトは昇順で、先頭に"-"(半角マイナス)を付けることで降順になります。
ex) sort=-review で口コミ件数の多い順にソート
start int 取得開始位置を指定します(最大3000)。
results int 取得件数を指定します(最大100)。
detail string
simple,
standard(デフォルト),
full
出力項目数を増減できます。詳細はこちらをご覧ください。
output string
xml(デフォルト),
json
出力形式を指定します:
  • xml - XML形式
  • json - JSON形式
callback string JSONPとして出力する際のコールバック関数名を入力するためのパラメータ。UTF-8でエンコードした文字列を入力します。
lat float 中心の緯度。
lon float 中心の経度。
dist float 検索距離(km)です。
最大20km、小数点も指定できます。
中心の緯度、中心の経度のパラメータが必須です。
bbox string 矩形範囲の左下経度、左下緯度、右上経度、右上緯度を世界測地系十進形式で指定(コンマ区切り)。
ac string 住所コード(日本工業規格(JIS) X 0401)または国コード(国際標準化機構(ISO) 3166-1 alpha-2)です。
住所コードは都道府県(2けた)と市町村(5けた)を指定可能です。
ex) 北海道:01, 札幌市中央区:01101
国コードは、2文字を指定してください。
ex) 日本:JP、アメリカ:US
gc string 業種コードを指定します。YOLP業種コードをご覧ください。
coupon boolean trueを指定すると、クーポンが利用できる店舗データを対象に検索します。falseは無効です。
※モバイル向けサイトでは掲載不可なクーポンがあります。APIの結果をモバイル端末に掲載する場合は、リクエストパラメータ「device」をセットし「mobile」を指定してください。モバイル端末で掲載不可なクーポンが非表示になります。
※クーポンの利用についてはクーポン提供元サイトの利用条件(画面を印刷して提示など)に準じます。
parking boolean trueを指定すると、駐車場がある店舗データを対象に検索します。falseは無効です
creditcard boolean trueを指定すると、クレジットカードが利用できる店舗データを対象に検索します。falseは無効です。
smoking string 喫煙の可否を指定して検索ができます。
コンマ「,」区切りで複数指定できます。
  • 1 - 禁煙
  • 2 - 分煙
  • 3 - 喫煙可
reservation string 1を指定すると、予約ができる店舗データを対象に検索します。
image boolean trueを指定すると、画像があるデータを対象に検索します。falseは無効です。
open string 特定の日時に開店している施設を検索します。
  • 日付と時間による検索 - date,hourで指定します。ex)5日の19時:5,19
    ・24時は0時として指定してください。
    ・指定できる日付は現在時刻から1週間後までです。
  • 曜日と時間による検索 - week,hourで指定します。ex)月曜日の12時:Mon,12
    ・曜日はMon,Tue,Wed,Thu,Fri,Sat,Sunのいずれかで指定します。
  • 現在時刻で開店している施設を検索 - nowで指定します。ex)現在時刻:now
loco_mode boolean 以下の検索機能を有効にします。
・3文字以下のひらがなまたはカタカナでのクエリのロジックが変更になります。より絞り込まれた結果が返ってくるようになります。
・「ランチ」「飲み放題」「食べ放題」「女子会」「個室」で検索した場合、自動的にフラグ検索に切り替わります。
  • 「ランチ」の場合は、LunchFlagがtrueのものが対象です。
  • 「飲み放題」の場合は、AllYouCanDrinkFlagがtrueのものが対象です。
  • 「食べ放題」の場合は、AllYouCanEatFlagがtrueのものが対象です。
  • 「女子会」の場合は、LadysPartyFlagがtrueのものが対象です。
  • 「個室」の場合は、PrivateDiningFlagがtrueのものが対象です。
デフォルト値はtrueで、falseを指定すると無効です。
maxprice int Priceタグの最大値を指定します。
minprice int Priceタグの最小値を指定します。

API使用上の注意

appid以外に緯度経度(lat,lon),uid,cid,query,acのいずれかのパラメータが必須となります。
URLの最大の長さは2048バイトです。エンコード後のURLの長さが2048バイトを超えないようにしてください。

サンプルリクエストURL

「電話帳」カセットを指定して、「六本木周辺2km以内のラーメン」を検索する場合の例です。

https://map.yahooapis.jp/search/local/V1/localSearch?cid=d8a23e9e64a4c817227ab09858bc1330&lat=35.662654694078626&lon=139.73135330250383&dist=2&query=%E3%83%A9%E3%83%BC%E3%83%A1%E3%83%B3&appid=<あなたのClient ID(アプリケーションID)>

レスポンスフィールド

フィールド 説明
YDF クエリーレスポンスのすべてを含みます。
 ResultInfo レスポンスのまとめ情報です。
  Count レスポンス情報に含まれるデータ件数です。
  Total 出力されている住所情報以外も含めた全データ件数です。
  Start レスポンス情報に含まれるデータの、全データからの取得開始位置です。
  Latency レスポンス情報を生成するのに要した時間です。
  Status リクエスト元に処理結果を伝えるためのコードです。正常終了の場合、200を出力します。エラー時は、下記エラー項目を参照してください。
 Feature 検索結果1件分のデータ群です。
  Id カセット内部のIDです。
  Gid 拠点ごとに割り当てられた拠点の管理IDです。
  Name 地域・拠点情報名です。
  Geometry 拠点の場所を表すGeometry要素です(世界測地系)。
   Type 図形種別です。
   Coordinates 座標情報です。
  Property 地域・拠点情報の詳細要素です。
   Uid Yahoo! Open Local Platform(YOLP)内部での識別IDです。
   CassetteId カセットIDです。
   Yomi 地域・拠点情報名の読みです。
   Country 国情報です。
    Code 国コード(国際標準化機構(ISO) 3166-1)です。
    Name 国名です。
   Address 1行で表す住所です。
   GovernmentCode 住所コード(日本工業規格(JIS) X 0401 5けた)です。
   Station 最寄駅情報です。最大3件です。
    Id 駅IDです。
    Name 駅名です。
    Railway 代表路線名です。
    Exit 最寄りの駅出口名です。
    ExitId 最寄りの駅出口IDです。
    Distance 最寄駅出口からの距離(m)です。
    Time 最寄駅出口からの徒歩時間です。
   PlaceInfo 店舗が入る場所情報を格納します。
    FloorName フロア名です。
    MapType 最適な地図の種別です。
    MapScale この地域・拠点名を表示するのに適切な地図の縮尺です。
   Tel1 電話番号です。
   Genre 店舗のジャンルです(※複数あり)。
    Code 業種コードです。
    Name ジャンル名です。
   Building ビル情報です。
    Id ビルごとに割り当てられたIDです。ビルIDは変更になる場合があります。
    Name ビル名です。
    Floor 階数の情報です。
   CatchCopy キャッチコピーです。
   Coupon クーポン情報です。
   ReviewCount レビュー数です。
   Detail 詳細情報です。
    ZipCode 郵便番号です。
    Fax1 Fax番号です。
    Access1 アクセス方法です。
    PcUrl1 パソコンサイトのURLです。
    MobileUrl1 モバイルサイトのURLです。
    ReviewUrl レビューのURLです。
    Image1 画像情報です。
   Style Style情報です。

こちらで定義されているレスポンスフィールドはデフォルトのものです。各カセットごとに拡張されたレスポンスフィールドを持つ場合があります。YDFの説明やスキーマの記述を参考にしてください。

サンプルレスポンス

「電話帳」カセットを指定して、「サントリー美術館」を検索した場合のサンプルリクエストとレスポンスです。

https://map.yahooapis.jp/search/local/V1/localSearch?cid=d8a23e9e64a4c817227ab09858bc1330&query=%E3%82%B5%E3%83%B3%E3%83%88%E3%83%AA%E3%83%BC%E7%BE%8E%E8%A1%93%E9%A4%A8&appid=<あなたのClient ID(アプリケーションID)>
<YDF xmlns="http://olp.yahooapis.jp/ydf/1.0" totalResultsReturned="1" totalResultsAvailable="1" firstResultPosition="1">
  <ResultInfo>
    <Count>1</Count>
    <Total>1</Total>
    <Start>1</Start>
    <Status>200</Status>
    <Description/>
    <Latency>0.037</Latency>
  </ResultInfo>
  <Feature>
    <Id>21331365961</Id>
    <Gid>SbydF0FVLUg</Gid>
    <Name>サントリー美術館</Name>
    <Geometry>
      <Type>point</Type>
      <Coordinates>139.729511666667,35.665818611111</Coordinates>
    </Geometry>
    <Category/>
    <Description/>
    <Style/>
    <Property>
      <Uid>5e807ebf7e656b712ba621c1a0b9ea68c5451919</Uid>
      <CassetteId>d8a23e9e64a4c817227ab09858bc1330</CassetteId>
      <Yomi>サントリービジュツカン</Yomi>
      <Country>
        <Code>JP</Code>
        <Name>日本</Name>
      </Country>
      <Address>東京都港区赤坂9丁目7−4</Address>
      <GovernmentCode>13103</GovernmentCode>
      <AddressMatchingLevel>6</AddressMatchingLevel>
      <Tel1>03-3479-8600</Tel1>
      <Genre>
        <Code>0305002</Code>
        <Name>美術館</Name>
      </Genre>
      <Area>
        <Code>000025</Code>
        <Name>赤坂・六本木</Name>
      </Area>
      <Station>
        <Id>22893</Id>
        <SubId>2289301</SubId>
        <Name>乃木坂</Name>
        <Railway>東京メトロ千代田線</Railway>
        <Exit>3</Exit>
        <ExitId>4913</ExitId>
        <Distance>349</Distance>
        <Time>4</Time>
      </Station>
      <Station>
        <Id>23049</Id>
        <SubId>2304901</SubId>
        <Name>六本木</Name>
        <Railway>都営大江戸線/東京メトロ日比谷線</Railway>
        <Exit>7</Exit>
        <ExitId>5423</ExitId>
        <Distance>378</Distance>
        <Time>4</Time>
      </Station>
      <Station>
        <Id>22893</Id>
        <SubId>2289301</SubId>
        <Name>乃木坂</Name>
        <Railway>東京メトロ千代田線</Railway>
        <Exit>4</Exit>
        <ExitId>4914</ExitId>
        <Distance>408</Distance>
        <Time>4</Time>
      </Station>
      <KeepCount>69</KeepCount>
    </Property>
  </Feature>
</YDF>

エラー

ローカルサーチAPIはYahoo! JAPAN Web APIに共通のエラーメッセージおよびコードを返します。

利用制限

ローカルサーチAPIは、24時間中1アプリケーションにつき50000件のリクエストが上限となっています。詳しくは「利用制限」をご参照ください。

アプリケーションの管理

目次

利用のルール

開発のヒント