郵便番号検索API

リクエストURL

XML
https://map.yahooapis.jp/search/zip/V1/zipCodeSearch
JSONP
https://map.yahooapis.jp/search/zip/V1/zipCodeSearch

リクエストURLは上記URLをご利用ください。AOSSL対応以前の旧URLは予告なくクローズします。

目次

概要

  • 郵便番号検索APIでは、郵便番号に関する情報を取得できます。
  • 郵便番号を指定して、位置情報（地点名・緯度・経度）と日本郵便の郵便番号名称を取得できます。

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

本APIは、GETメソッドのみサポートしています。「Web APIの使い方#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 出力項目数を増減できます。詳細はこちらをご覧ください。
  • simple - 簡易
  • standard - 標準（デフォルト）
  • full - 詳細
output string 出力形式：
  • xml - XML形式（デフォルト）
  • json - JSON形式
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 住所構造のレベルです。
  • prefecture - 都道府県
  • city - 市区町村
  • oaza - 大字
  • aza - 字
　　　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>

アプリケーションの管理

目次

開発のヒント