郵便番号と日付で、その日の行をすべて取得する

GET

/postal-codes/{postal_code}

const url = 'https://api.strata.lambdado.com/v1/postal-codes/example';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.strata.lambdado.com/v1/postal-codes/example \
  --header 'Authorization: Bearer <token>'

日本郵便のデータの 1 行が、entries の 1 件になる。1 つの郵便番号に複数の行があることがあり、それらの行が別々の市区町村に属することもある。

行の有効期間は、日本郵便のデータにその行が載っていた期間で、法的な効力の期間とは別である。ただし、行政区域の変更による行の入れ替えは、その変更の施行日に合わせてある。

町域名と事業所名は、日本郵便のデータの表記のまま返す（括弧書きや「以下に掲載がない場合」も含む）。読みは全角カタカナで返す。事業所の行の読みは、日本郵便のデータの半角カナを全角に変換したもの。

Authorizations

apiKey

Parameters

Path Parameters

postal_code

required

string

/^\d{7}$/

7 桁の数字。ハイフンを含むと 400

Query Parameters

string format: date

/^\d{4}-\d{2}-\d{2}$/

日本の暦の日付。省略すると日本時間の今日。時刻を含む値（2026-01-01T09:00+09:00 など）は 400

Responses

200

その日の行

application/json

object

required

string format: date

/^\d{4}-\d{2}-\d{2}$/

projected

required

At が、sources に載ったどれかのデータの known_through より後。今分かっている最新の状態が続くとみなした答えで、新しいデータを取り込むと変わりうる。404 では、同じエンドポイントが 200 で返す sources のデータで決まる

boolean

postal_code

required

string

/^\d{7}$/

entries

required

市区町村・区のコード、町域名の読みの昇順

Array<object>

>= 1 items

object

kind

required

住所の郵便番号の行か、事業所の個別郵便番号の行か

string

Allowed values: address office

town_name

required

string

town_name_kana

required

One of:

string
null

string

flags

required

One of:

object
null

日本郵便のデータの表示のうち、更新のたびに変わらない 4 つ

object

town_has_multiple_postal_codes

required

一町域が二以上の郵便番号で表される

boolean

numbered_by_koaza

required

小字毎に番地が起番されている

boolean

has_chome

required

丁目を有する

boolean

postal_code_has_multiple_towns

required

一つの郵便番号で二以上の町域を表す

boolean

office

required

One of:

object
null

object

name

required

string

name_kana

required

全角カタカナ

string

address

required

町域より後の、小字・丁目・番地

string

post_office

required

取扱局

string

type

required

大口事業所か私書箱か

string

Allowed values: large_volume po_box

prefecture

required

object

level

required

都道府県、市区町村（東京の特別区を含む）、政令市の区

string

Allowed values: prefecture municipality ward

code

required

string

/^(\d{2}|\d{5})$/

name

required

string

municipality

required

object

level

required

都道府県、市区町村（東京の特別区を含む）、政令市の区

string

Allowed values: prefecture municipality ward

code

required

string

/^(\d{2}|\d{5})$/

name

required

string

ward

required

One of:

object
null

object

level

required

都道府県、市区町村（東京の特別区を含む）、政令市の区

string

Allowed values: prefecture municipality ward

code

required

string

/^(\d{2}|\d{5})$/

name

required

string

valid_since

required

この日を含む

string format: date

/^\d{4}-\d{2}-\d{2}$/

valid_until

required

One of:

string
null

string format: date

/^\d{4}-\d{2}-\d{2}$/

scheduled

required

Valid_since が日本時間の今日より後なら true。at ではなく呼び出した日で決まるので、同じ at でも valid_since を過ぎてから呼び出すと false になる

boolean

sources

required

Array<object>

応答に使ったデータの種類ごとの出典。データ源の利用条件が求める表示は attribution をそのまま出せば満たせる

object

dataset

required

string

Allowed values: administrative_areas postal_codes minimum_wages

publisher

required

string

title

required

string

url

required

string format: uri

license

required

データ源の利用条件

object

name

required

string

url

required

string format: uri

attribution

required

出典と、このサービスが加工したことを示す表示用の文

string

updated_on

required

このサービスがこのデータを最後に更新した日。訂正したときも変わる

string format: date

/^\d{4}-\d{2}-\d{2}$/

known_through

required

このデータで分かる最後の日付。at がこの日以前なら、新しいデータを取り込んでも応答は変わらない

string format: date

/^\d{4}-\d{2}-\d{2}$/

Examples

尾花沢市と大石田町にまたがる郵便番号

{
  "at": "2026-10-03",
  "projected": true,
  "postal_code": "9994554",
  "entries": [
    {
      "kind": "address",
      "town_name": "芦沢",
      "town_name_kana": "アシザワ",
      "flags": {
        "town_has_multiple_postal_codes": false,
        "numbered_by_koaza": false,
        "has_chome": false,
        "postal_code_has_multiple_towns": true
      },
      "office": null,
      "prefecture": {
        "level": "prefecture",
        "code": "06",
        "name": "山形県"
      },
      "municipality": {
        "level": "municipality",
        "code": "06212",
        "name": "尾花沢市"
      },
      "ward": null,
      "valid_since": "2023-04-28",
      "valid_until": null,
      "scheduled": false
    },
    {
      "kind": "address",
      "town_name": "鷹巣（岡草山）",
      "town_name_kana": "タカノス（オカクサヤマ）",
      "flags": {
        "town_has_multiple_postal_codes": true,
        "numbered_by_koaza": true,
        "has_chome": false,
        "postal_code_has_multiple_towns": true
      },
      "office": null,
      "prefecture": {
        "level": "prefecture",
        "code": "06",
        "name": "山形県"
      },
      "municipality": {
        "level": "municipality",
        "code": "06341",
        "name": "大石田町"
      },
      "ward": null,
      "valid_since": "2023-04-28",
      "valid_until": null,
      "scheduled": false
    }
  ],
  "sources": [
    {
      "dataset": "postal_codes",
      "publisher": "日本郵便株式会社",
      "title": "郵便番号データ",
      "url": "https://www.post.japanpost.jp/service/search/zipcode/download/",
      "license": {
        "name": "日本郵便は著作権を主張しない",
        "url": "https://www.post.japanpost.jp/service/search/zipcode/download/readme.html"
      },
      "attribution": "「郵便番号データ」（日本郵便株式会社）（https://www.post.japanpost.jp/service/search/zipcode/download/）を加工して strata が作成",
      "updated_on": "2026-10-01",
      "known_through": "2026-09-30"
    },
    {
      "dataset": "administrative_areas",
      "publisher": "独立行政法人統計センター",
      "title": "統計LOD 標準地域コード",
      "url": "https://data.e-stat.go.jp/lodw/provdata/lodRegion",
      "license": {
        "name": "CC BY 4.0",
        "url": "https://creativecommons.org/licenses/by/4.0/legalcode.ja"
      },
      "attribution": "「統計LOD 標準地域コード」（独立行政法人統計センター）（https://data.e-stat.go.jp/lodw/provdata/lodRegion）を加工して strata が作成（CC BY 4.0、https://creativecommons.org/licenses/by/4.0/legalcode.ja）",
      "updated_on": "2026-10-01",
      "known_through": "2026-10-01"
    },
    {
      "dataset": "administrative_areas",
      "publisher": "総務省統計局・独立行政法人統計センター",
      "title": "e-Stat 廃置分合等情報",
      "url": "https://www.e-stat.go.jp/municipalities/cities/absorption-separation-of-municipalities",
      "license": {
        "name": "政府統計の総合窓口(e-Stat) 利用規約",
        "url": "https://www.e-stat.go.jp/terms-of-use"
      },
      "attribution": "出典：政府統計の総合窓口(e-Stat)（https://www.e-stat.go.jp/）。「廃置分合等情報」を加工して strata が作成",
      "updated_on": "2026-10-01",
      "known_through": "2026-10-01"
    }
  ]
}

区の再編の前日。日本郵便は 2023-11-30 に行を入れ替えたが、施行日の 2024-01-01 まで古い区を返す

{
  "at": "2023-12-31",
  "projected": false,
  "postal_code": "4313425",
  "entries": [
    {
      "kind": "address",
      "town_name": "青谷",
      "town_name_kana": "アオヤ",
      "flags": {
        "town_has_multiple_postal_codes": false,
        "numbered_by_koaza": false,
        "has_chome": false,
        "postal_code_has_multiple_towns": false
      },
      "office": null,
      "prefecture": {
        "level": "prefecture",
        "code": "22",
        "name": "静岡県"
      },
      "municipality": {
        "level": "municipality",
        "code": "22130",
        "name": "浜松市"
      },
      "ward": {
        "level": "ward",
        "code": "22137",
        "name": "天竜区"
      },
      "valid_since": "2023-04-28",
      "valid_until": "2024-01-01",
      "scheduled": false
    }
  ],
  "sources": [
    {
      "dataset": "postal_codes",
      "publisher": "日本郵便株式会社",
      "title": "郵便番号データ",
      "url": "https://www.post.japanpost.jp/service/search/zipcode/download/",
      "license": {
        "name": "日本郵便は著作権を主張しない",
        "url": "https://www.post.japanpost.jp/service/search/zipcode/download/readme.html"
      },
      "attribution": "「郵便番号データ」（日本郵便株式会社）（https://www.post.japanpost.jp/service/search/zipcode/download/）を加工して strata が作成",
      "updated_on": "2026-10-01",
      "known_through": "2026-09-30"
    },
    {
      "dataset": "administrative_areas",
      "publisher": "独立行政法人統計センター",
      "title": "統計LOD 標準地域コード",
      "url": "https://data.e-stat.go.jp/lodw/provdata/lodRegion",
      "license": {
        "name": "CC BY 4.0",
        "url": "https://creativecommons.org/licenses/by/4.0/legalcode.ja"
      },
      "attribution": "「統計LOD 標準地域コード」（独立行政法人統計センター）（https://data.e-stat.go.jp/lodw/provdata/lodRegion）を加工して strata が作成（CC BY 4.0、https://creativecommons.org/licenses/by/4.0/legalcode.ja）",
      "updated_on": "2026-10-01",
      "known_through": "2026-10-01"
    },
    {
      "dataset": "administrative_areas",
      "publisher": "総務省統計局・独立行政法人統計センター",
      "title": "e-Stat 廃置分合等情報",
      "url": "https://www.e-stat.go.jp/municipalities/cities/absorption-separation-of-municipalities",
      "license": {
        "name": "政府統計の総合窓口(e-Stat) 利用規約",
        "url": "https://www.e-stat.go.jp/terms-of-use"
      },
      "attribution": "出典：政府統計の総合窓口(e-Stat)（https://www.e-stat.go.jp/）。「廃置分合等情報」を加工して strata が作成",
      "updated_on": "2026-10-01",
      "known_through": "2026-10-01"
    }
  ]
}

区の再編の当日。新しい天竜区のコードを返す

{
  "at": "2024-01-01",
  "projected": false,
  "postal_code": "4313425",
  "entries": [
    {
      "kind": "address",
      "town_name": "青谷",
      "town_name_kana": "アオヤ",
      "flags": {
        "town_has_multiple_postal_codes": false,
        "numbered_by_koaza": false,
        "has_chome": false,
        "postal_code_has_multiple_towns": false
      },
      "office": null,
      "prefecture": {
        "level": "prefecture",
        "code": "22",
        "name": "静岡県"
      },
      "municipality": {
        "level": "municipality",
        "code": "22130",
        "name": "浜松市"
      },
      "ward": {
        "level": "ward",
        "code": "22140",
        "name": "天竜区"
      },
      "valid_since": "2024-01-01",
      "valid_until": null,
      "scheduled": false
    }
  ],
  "sources": [
    {
      "dataset": "postal_codes",
      "publisher": "日本郵便株式会社",
      "title": "郵便番号データ",
      "url": "https://www.post.japanpost.jp/service/search/zipcode/download/",
      "license": {
        "name": "日本郵便は著作権を主張しない",
        "url": "https://www.post.japanpost.jp/service/search/zipcode/download/readme.html"
      },
      "attribution": "「郵便番号データ」（日本郵便株式会社）（https://www.post.japanpost.jp/service/search/zipcode/download/）を加工して strata が作成",
      "updated_on": "2026-10-01",
      "known_through": "2026-09-30"
    },
    {
      "dataset": "administrative_areas",
      "publisher": "独立行政法人統計センター",
      "title": "統計LOD 標準地域コード",
      "url": "https://data.e-stat.go.jp/lodw/provdata/lodRegion",
      "license": {
        "name": "CC BY 4.0",
        "url": "https://creativecommons.org/licenses/by/4.0/legalcode.ja"
      },
      "attribution": "「統計LOD 標準地域コード」（独立行政法人統計センター）（https://data.e-stat.go.jp/lodw/provdata/lodRegion）を加工して strata が作成（CC BY 4.0、https://creativecommons.org/licenses/by/4.0/legalcode.ja）",
      "updated_on": "2026-10-01",
      "known_through": "2026-10-01"
    },
    {
      "dataset": "administrative_areas",
      "publisher": "総務省統計局・独立行政法人統計センター",
      "title": "e-Stat 廃置分合等情報",
      "url": "https://www.e-stat.go.jp/municipalities/cities/absorption-separation-of-municipalities",
      "license": {
        "name": "政府統計の総合窓口(e-Stat) 利用規約",
        "url": "https://www.e-stat.go.jp/terms-of-use"
      },
      "attribution": "出典：政府統計の総合窓口(e-Stat)（https://www.e-stat.go.jp/）。「廃置分合等情報」を加工して strata が作成",
      "updated_on": "2026-10-01",
      "known_through": "2026-10-01"
    }
  ]
}

事業所の個別郵便番号

{
  "at": "2025-10-31",
  "projected": false,
  "postal_code": "8808566",
  "entries": [
    {
      "kind": "office",
      "town_name": "別府町",
      "town_name_kana": null,
      "flags": null,
      "office": {
        "name": "宮崎地方検察庁",
        "name_kana": "ミヤザキチホウケンサツチヨウ",
        "address": "１－１",
        "post_office": "宮崎中央",
        "type": "large_volume"
      },
      "prefecture": {
        "level": "prefecture",
        "code": "45",
        "name": "宮崎県"
      },
      "municipality": {
        "level": "municipality",
        "code": "45201",
        "name": "宮崎市"
      },
      "ward": null,
      "valid_since": "2025-10-31",
      "valid_until": null,
      "scheduled": false
    }
  ],
  "sources": [
    {
      "dataset": "postal_codes",
      "publisher": "日本郵便株式会社",
      "title": "郵便番号データ",
      "url": "https://www.post.japanpost.jp/service/search/zipcode/download/",
      "license": {
        "name": "日本郵便は著作権を主張しない",
        "url": "https://www.post.japanpost.jp/service/search/zipcode/download/readme.html"
      },
      "attribution": "「郵便番号データ」（日本郵便株式会社）（https://www.post.japanpost.jp/service/search/zipcode/download/）を加工して strata が作成",
      "updated_on": "2026-10-01",
      "known_through": "2026-09-30"
    },
    {
      "dataset": "administrative_areas",
      "publisher": "独立行政法人統計センター",
      "title": "統計LOD 標準地域コード",
      "url": "https://data.e-stat.go.jp/lodw/provdata/lodRegion",
      "license": {
        "name": "CC BY 4.0",
        "url": "https://creativecommons.org/licenses/by/4.0/legalcode.ja"
      },
      "attribution": "「統計LOD 標準地域コード」（独立行政法人統計センター）（https://data.e-stat.go.jp/lodw/provdata/lodRegion）を加工して strata が作成（CC BY 4.0、https://creativecommons.org/licenses/by/4.0/legalcode.ja）",
      "updated_on": "2026-10-01",
      "known_through": "2026-10-01"
    },
    {
      "dataset": "administrative_areas",
      "publisher": "総務省統計局・独立行政法人統計センター",
      "title": "e-Stat 廃置分合等情報",
      "url": "https://www.e-stat.go.jp/municipalities/cities/absorption-separation-of-municipalities",
      "license": {
        "name": "政府統計の総合窓口(e-Stat) 利用規約",
        "url": "https://www.e-stat.go.jp/terms-of-use"
      },
      "attribution": "出典：政府統計の総合窓口(e-Stat)（https://www.e-stat.go.jp/）。「廃置分合等情報」を加工して strata が作成",
      "updated_on": "2026-10-01",
      "known_through": "2026-10-01"
    }
  ]
}

町域名は日本郵便の表記のまま返す

{
  "at": "2026-10-03",
  "projected": true,
  "postal_code": "2520100",
  "entries": [
    {
      "kind": "address",
      "town_name": "以下に掲載がない場合",
      "town_name_kana": "イカニケイサイガナイバアイ",
      "flags": {
        "town_has_multiple_postal_codes": false,
        "numbered_by_koaza": false,
        "has_chome": false,
        "postal_code_has_multiple_towns": false
      },
      "office": null,
      "prefecture": {
        "level": "prefecture",
        "code": "14",
        "name": "神奈川県"
      },
      "municipality": {
        "level": "municipality",
        "code": "14150",
        "name": "相模原市"
      },
      "ward": {
        "level": "ward",
        "code": "14151",
        "name": "緑区"
      },
      "valid_since": "2023-04-28",
      "valid_until": null,
      "scheduled": false
    }
  ],
  "sources": [
    {
      "dataset": "postal_codes",
      "publisher": "日本郵便株式会社",
      "title": "郵便番号データ",
      "url": "https://www.post.japanpost.jp/service/search/zipcode/download/",
      "license": {
        "name": "日本郵便は著作権を主張しない",
        "url": "https://www.post.japanpost.jp/service/search/zipcode/download/readme.html"
      },
      "attribution": "「郵便番号データ」（日本郵便株式会社）（https://www.post.japanpost.jp/service/search/zipcode/download/）を加工して strata が作成",
      "updated_on": "2026-10-01",
      "known_through": "2026-09-30"
    },
    {
      "dataset": "administrative_areas",
      "publisher": "独立行政法人統計センター",
      "title": "統計LOD 標準地域コード",
      "url": "https://data.e-stat.go.jp/lodw/provdata/lodRegion",
      "license": {
        "name": "CC BY 4.0",
        "url": "https://creativecommons.org/licenses/by/4.0/legalcode.ja"
      },
      "attribution": "「統計LOD 標準地域コード」（独立行政法人統計センター）（https://data.e-stat.go.jp/lodw/provdata/lodRegion）を加工して strata が作成（CC BY 4.0、https://creativecommons.org/licenses/by/4.0/legalcode.ja）",
      "updated_on": "2026-10-01",
      "known_through": "2026-10-01"
    },
    {
      "dataset": "administrative_areas",
      "publisher": "総務省統計局・独立行政法人統計センター",
      "title": "e-Stat 廃置分合等情報",
      "url": "https://www.e-stat.go.jp/municipalities/cities/absorption-separation-of-municipalities",
      "license": {
        "name": "政府統計の総合窓口(e-Stat) 利用規約",
        "url": "https://www.e-stat.go.jp/terms-of-use"
      },
      "attribution": "出典：政府統計の総合窓口(e-Stat)（https://www.e-stat.go.jp/）。「廃置分合等情報」を加工して strata が作成",
      "updated_on": "2026-10-01",
      "known_through": "2026-10-01"
    }
  ]
}

400

パラメータが正しくない

application/problem+json

説明

object

type

required

Allowed value: tag:lambdado.com,2026:strata/problems/invalid-parameter

title

required

string

status

required

integer

detail

string

parameter

required

string

Examples

hyphen

郵便番号は 7 桁の数字だけ。ハイフンは受け付けない

{
  "type": "tag:lambdado.com,2026:strata/problems/invalid-parameter",
  "title": "Invalid parameter",
  "status": 400,
  "detail": "postal_code must be 7 digits without a hyphen",
  "parameter": "postal_code"
}

401

API キーがない・正しくない・失効している、または組織が停止されている

application/problem+json

説明

object

type

required

Allowed value: tag:lambdado.com,2026:strata/problems/unauthorized

title

required

string

status

required

integer

detail

string

Examples

Authorization を付けていない

{
  "type": "tag:lambdado.com,2026:strata/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authorization header with a Bearer API key is required"
}

失効したキーを使った

{
  "type": "tag:lambdado.com,2026:strata/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key is invalid or revoked"
}

Headers

WWW-Authenticate

required

string

Authorization がないか Bearer 以外の方式なら Bearer、Bearer で渡したキーが無効なら Bearer error="invalid_token"（RFC 6750）

Examples

Authorization を付けていない、または Bearer 以外の方式

Bearer

Bearer で渡したキーが無効

Bearer error="invalid_token"

404

その日にその郵便番号の行がない

application/problem+json

説明

object

type

required

Allowed value: tag:lambdado.com,2026:strata/problems/postal-code-not-found

title

required

string

status

required

integer

detail

string

postal_code

required

string

/^\d{7}$/

required

string format: date

/^\d{4}-\d{2}-\d{2}$/

projected

required

boolean

Examples

reused

戸原の行が削除されてから、江辻西の行が追加されるまでの 811-2312

{
  "type": "tag:lambdado.com,2026:strata/problems/postal-code-not-found",
  "title": "No entry has this postal code on this date",
  "status": 404,
  "postal_code": "8112312",
  "at": "2025-01-01",
  "projected": false
}

422

郵便番号の履歴の起点より前

application/problem+json

説明

object

type

required

Allowed value: tag:lambdado.com,2026:strata/problems/out-of-coverage

title

required

string

status

required

integer

detail

string

dataset

required

string

Allowed values: administrative_areas postal_codes minimum_wages

coverage_since

required

このデータ（最低賃金の一覧なら、いちばん遅い都道府県）の履歴の起点

string format: date

/^\d{4}-\d{2}-\d{2}$/

Examples

beforeCoverage

{
  "type": "tag:lambdado.com,2026:strata/problems/out-of-coverage",
  "title": "The date is before the history this API holds",
  "status": 422,
  "dataset": "postal_codes",
  "coverage_since": "2023-04-28"
}

429

組織の上限を超えた

application/problem+json

説明

object

type

required

Allowed value: tag:lambdado.com,2026:strata/problems/too-many-requests

title

required

string

status

required

integer

detail

string

window

required

超えた上限。minute は 1 分あたり、month は日本時間の暦月あたり

Allowed values: minute month

limit

required

超えた上限の回数

integer

Examples

月の上限を超えた

{
  "type": "tag:lambdado.com,2026:strata/problems/too-many-requests",
  "title": "Too many requests",
  "status": 429,
  "detail": "monthly limit of 10000 requests reached",
  "window": "month",
  "limit": 10000
}

1 分あたりの上限を超えた

{
  "type": "tag:lambdado.com,2026:strata/problems/too-many-requests",
  "title": "Too many requests",
  "status": 429,
  "detail": "per-minute limit of 60 requests reached",
  "window": "minute",
  "limit": 60
}

Headers

Retry-After

required

integer

次に呼び出せるまでの秒数。月の上限なら日本時間の翌月 1 日 0 時まで、1 分の上限なら次の分まで（1〜60）