YOLP(地図)
郵便番号検索API
【重要】常時SSL(AOSSL)対応にともないリクエストURLが変更されています。詳しくはこちらをご確認ください。リクエストURL
XML
https://map.yahooapis.jp/search/zip/V1/zipCodeSearch
JSONP
https://map.yahooapis.jp/search/zip/V1/zipCodeSearch
目次
概要
- 郵便番号検索APIでは、郵便番号に関する情報を取得できます。
- 郵便番号を指定して、位置情報(地点名・緯度・経度)と日本郵便の郵便番号名称を取得できます。
リクエストパラメーター一覧
「RESTリクエストの構築(GET)」をご参照ください。
パラメーター | 値 | 説明 |
---|---|---|
appid(必須) | string | アプリケーションIDです。詳細はこちらをご覧ください。 |
query | string | 検索クエリーです。文字コードはUTF-8をサポートしています。URLエンコードをしてください。 |
ac | string | 住所コード(JIS X 0401)を指定してください。 住所コードは都道府県(2桁)と市区町村(5桁)を指定可能です。 ex) 北海道:01, 札幌市中央区:01101 日本全国の場合は、国コード(JP)を指定してください。 |
sort | string | 並べ替え形式を指定してください。 zip_code : 郵便番号を昇順でソートします(デフォルト) -zip_code : 郵便番号を降順でソートします zip_kana : 住所文字列のカナコードを昇順でソートします -zip_kana : 住所文字列のカナコードを降順でソートします |
zkind | string | 郵便番号種別を指定してください。 0:町域郵便番号 1:ビル郵便番号 2:市区郡町村の代表郵便番号 3:大口事業所郵便番号 4:私書箱郵便番号 コンマ「,」区切りで複数指定できます。 |
results | int | 取得件数を指定します(デフォルト10、最大100)。 |
start | int | 取得開始位置を指定します(デフォルト1、最大3000)。 |
detail | string | 出力項目数を増減できます。詳細はこちらをご覧ください。
|
output | string | 出力形式:
|
callback | string |
JSONPとして出力する際のコールバック関数名を入力するためのパラメーター。UTF-8でエンコードした文字列を入力します。 |
サンプルリクエスト
郵便番号〒105-0011のリクエストです。
https://map.yahooapis.jp/search/zip/V1/zipCodeSearch?query=105-0011&appid=<あなたのアプリケーションID>
API使用上の注意
URLの最大の長さは2048バイトです。
URLをエンコードして指定するパラメーターもありますが、エンコード後のURLの長さが2048バイトをこえないようにしてください。
レスポンス
出力形式にXMLを指定(output=xml)の場合、XMLを返します。レスポンスフィールドをご参照ください。
レスポンスフィールド
フィールド | 説明 |
---|---|
YDF | クエリーレスポンスのすべてを含みます。 |
ResultInfo | レスポンスのまとめ情報です。 |
Count | レスポンス情報に含まれるデータ件数です。 |
Total | 出力されている全データ件数です。 |
Start | レスポンス情報に含まれる、全データからの取得開始位置です。 |
Status | リクエスト元に処理結果を伝えるためのコードです。正常終了の場合、200を出力します。エラー時は、下記エラー項目を参照してください。 |
Description | APIの説明文です。 |
Copyright | コピーライトです。 |
Latency | レスポンス情報を生成するのに要した時間です。 |
Feature | 検索結果1件分のデータ群です。 |
Id | カセット内部のIDです。 |
Name | 名称で郵便番号が格納されます。 |
Geometry | 場所を表すGeometry要素です(世界測地系)。 |
Type | 図形種別です。 |
Coordinates | 座標情報です。 |
Category | カテゴリーです。 |
Description | 説明文です。 |
Style | アイコン情報です。 |
Property | 各種データを格納します。 |
Uid | Yahoo! Open Local Platform(YOLP)内部でのユニークな識別IDです。 |
CassetteId | カセットIDです。 ※「3ee7f7f5fe1ef2267e319b15168e37d3」固定。 |
Country | 国情報です。 |
Code | 国コード(ISO 3166-1)です。 |
Name | 国名です。 |
Address | 住所文字列です。 |
AddressElement | 住所構造のデータ群です。リクエストパラメータのdetailを、詳細(full)で指定すると取得できます。 |
Name | 住所構造データの住所名称です。 |
Kana | 住所構造データの住所の読み(ひらがな)です。 |
Level | 住所構造のレベルです。
|
GovernmentCode | 住所コード(JIS X 0401 5桁)です。 |
PostalName | 郵便番号の名称です。 |
Station | 最寄り駅情報です。 最大3件です。 |
Id | 駅IDです。 |
SubId | 駅の出口IDです。 |
Name | 駅名です。 |
Railway | 代表路線名です。 |
Exit | 最寄りの駅出口名です。 |
ExitId | 最寄りの駅出口IDです。 |
Distance | 最寄り駅出口からの距離(m)です。 |
Time | 最寄り駅出口からの移動時間(分)です。 |
Geometry | 場所を表すGeometry要素です(世界測地系)。 |
Type | 図形種別です。 |
Coordinates | 座標情報です。 |
サンプルレスポンス
郵便番号〒105-0011のレスポンスです。
<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/> <Copyright/> <Latency>0.023</Latency> </ResultInfo> <Feature> <Id>d30c42d8a8cb04ee730d1e5846ea2a8a</Id> <Gid/> <Name>〒105-0011</Name> <Geometry> <Type>point</Type> <Coordinates>139.74816650,35.65757726</Coordinates> </Geometry> <Category>郵便番号</Category> <Category>町域郵便番号</Category> <Description>Yahoo!郵便番号検索</Description> <Style/> <Property> <Uid>2281d2dd75f52ee9ef0ba86149310b0cf710aedd</Uid> <CassetteId>3ee7f7f5fe1ef2267e319b15168e37d3</CassetteId> <Country> <Code>JP</Code> <Name>日本</Name> </Country> <Address>東京都港区芝公園</Address> <GovernmentCode>13103</GovernmentCode> <AddressMatchingLevel>6</AddressMatchingLevel> <PostalName>東京都港区芝公園</PostalName> <Station> <Id>22584</Id> <SubId>2258401</SubId> <Name>御成門</Name> <Railway>都営三田線</Railway> <Exit>A1</Exit> <ExitId>3607</ExitId> <Distance/> <Time>6</Time> <Geometry> <Type>point</Type> <Coordinates>139.7504467,35.6594219</Coordinates> </Geometry> </Station> <Station> <Id>22712</Id> <SubId>2271201</SubId> <Name>芝公園</Name> <Railway>都営三田線</Railway> <Exit>A4</Exit> <ExitId>4055</ExitId> <Distance/> <Time>8</Time> <Geometry> <Type>point</Type> <Coordinates>139.7497167,35.6544875</Coordinates> </Geometry> </Station> <Station> <Id>22815</Id> <SubId>2281501</SubId> <Name>大門(東京都)</Name> <Railway>都営浅草線/都営大江戸線</Railway> <Exit>A6</Exit> <ExitId>4541</ExitId> <Distance/> <Time>8</Time> <Geometry> <Type>point</Type> <Coordinates>139.7539208,35.6569678</Coordinates> </Geometry> </Station> </Property> </Feature> </YDF>
エラー
コード | 説明 |
---|---|
400 | 渡されたパラメーターがWeb APIで期待されたものと一致しない場合に返されます。 |
403 | リソースへのアクセスを許されていないか、利用制限をこえている場合に適用されます。 |
404 | 指定されたリソースが見つからない場合に返されます。 |
500 | 内部的な問題によってデータを返すことができない場合に返されます。 |
503 | 内部的な問題によってデータを返すことができない場合に返されます。 |
以下は、リクエストに対するエラーレスポンスです。
<?xml version="1.0" encoding="utf-8" ?> <Error> <Detail></Detail> <Code>403</Code> </Error>