{"openapi":"3.1.0","info":{"title":"Japan Business & Text Utilities API","version":"1.0.0","description":"Deterministic utilities for Japanese business data, built on official open data and served from the edge. No LLM, no async jobs: every endpoint answers synchronously, and the same input always gives the same output.\n\n**Six families.** Corporate numbers (search 5.8 million NTA registrations, resolve a messy name to one company, fetch a full record), addresses and postal codes (normalise a free-form address, look up or search postal codes, romanise for shipping labels), calendar (public holidays, business days with the year-end shutdown, Japanese era years), plus text conversion (furigana, romaji, kana, normalisation), personal-name readings and format validation (phone, postal code, corporate number).\n\n**Batching.** `POST /v1/batch` runs up to 100 of these calls in one request and counts as a single Request. It is available on the MEGA plan.\n\n**Envelope.** Success is `{ \"ok\": true, \"data\": ..., \"meta\": { \"dataset\", \"sources\", \"elapsed_ms\" } }`. Errors are `{ \"ok\": false, \"error\": { \"code\", \"message\", \"field\"?, \"hint\"? } }` with codes `invalid_input` (400), `unauthorized` (401), `plan_required` / `blocked` (403), `payload_too_large` (413), `free_tier_busy` / `free_tier_shared_limit` (429), `dataset_unavailable` (503) and `internal` (500). \"No match\" is not an error: it is 200 with an empty list (or `data: null` for `GET /v1/corporate/{number}`).\n\n**Authentication.** Send `X-RapidAPI-Key` and `X-RapidAPI-Host` as with any RapidAPI product; the gateway adds the proxy secret this API checks. `GET /v1/health` and `GET /v1/openapi.json` are the only endpoints that need no key.\n\n**Freshness.** `meta.dataset` carries the reference date of each dataset used by the call (corporate: the last daily update applied), and `GET /v1/datasets` lists them all. Corporate data is reimported in full every month and topped up daily from the NTA diff API; postal codes, holidays and the name dictionary are refreshed monthly.\n\n**Attribution.** Show these when you display the data:\n- 出典：国税庁法人番号公表サイト（国税庁）（https://www.houjin-bangou.nta.go.jp/）を加工して作成\n- 郵便番号データ：日本郵便株式会社（https://www.post.japanpost.jp/zipcode/）\n- 出典：内閣府「国民の祝日について」（https://www8.cao.go.jp/chosei/shukujitsu/gaiyou.html）\n- JMnedict © EDRDG, CC BY-SA 3.0（https://www.edrdg.org/）\n- 形態素解析：Lindera（MIT）+ IPADIC（BSD 風ライセンス、奈良先端科学技術大学院大学）\n\nThis API performs mechanical conversion and lookup of public data. It does not provide legal judgement, and corporate records are only as current as the date shown in `meta.dataset`."},"servers":[{"url":"https://jp.yosuga.dev"}],"tags":[{"name":"Corporate","description":"Corporate numbers (法人番号) from the National Tax Agency."},{"name":"Address","description":"Japanese address parsing and romanisation."},{"name":"Postal","description":"Postal codes (郵便番号) from Japan Post."},{"name":"Text","description":"Japanese text conversion: furigana, romaji, kana, normalisation."},{"name":"Name","description":"Personal name splitting and readings."},{"name":"Calendar","description":"Public holidays, business days and Japanese era years."},{"name":"Validate","description":"Format validation for Japanese identifiers."},{"name":"Batch","description":"Many calls in one request (MEGA)."},{"name":"Meta","description":"Health, dataset versions and plan limits."}],"paths":{"/v1/corporate/search":{"get":{"tags":["Corporate"],"operationId":"searchCorporations","summary":"Search companies by name (kanji, kana, half-width kana, old glyphs or English)","description":"Full-text search over every corporation registered with Japan's National Tax Agency (about 5.8 million rows). The query is normalised the same way the index is (NFKC, old glyphs to new, half-width kana to full-width, corporation kind such as 株式会社 or （株） removed), so `（株）トヨタ自動車`, `ｿﾌﾄﾊﾞﾝｸｸﾞﾙｰﾌﾟ` and `髙島屋` all hit the right company; English queries such as `MITSUBISHI ELECTRIC`, `RAKUTEN GROUP` or `TOYOTA MOTOR` match `en_name`, which comes from the NTA's registered English names (about 15,000 companies) plus the FSA's EDINET code list for listed companies (about 4,300). `match` tells you which stage matched: `exact_key` (normalised name is identical), `prefix`, `kana`, `en` (English name), `fts` (trigram full-text). `score` is 0-1 and the list is sorted by it. Closed registrations are excluded unless `include_closed=true`. Companies the NTA excludes from its own search (registered head-office address abolished by address renumbering or land readjustment, about 40,000) are never returned here or by resolve; look them up by number.\n\nBASIC returns at most 5 results (paid plans default to 20, `limit` up to 50); `meta.plan_limits` echoes the caps in force.","parameters":[{"name":"q","in":"query","required":true,"description":"Company name. Kind suffixes/prefixes are stripped before matching.","schema":{"type":"string","minLength":1,"maxLength":100},"example":"トヨタ自動車"},{"name":"prefecture","in":"query","required":false,"description":"Restrict to one prefecture: the full name of one of the 47 prefectures, e.g. 愛知県 (anything else returns 400).","schema":{"type":"string","x-jp-options":["北海道","青森県","岩手県","宮城県","秋田県","山形県","福島県","茨城県","栃木県","群馬県","埼玉県","千葉県","東京都","神奈川県","新潟県","富山県","石川県","福井県","山梨県","長野県","岐阜県","静岡県","愛知県","三重県","滋賀県","京都府","大阪府","兵庫県","奈良県","和歌山県","鳥取県","島根県","岡山県","広島県","山口県","徳島県","香川県","愛媛県","高知県","福岡県","佐賀県","長崎県","熊本県","大分県","宮崎県","鹿児島県","沖縄県"]},"example":"愛知県"},{"name":"limit","in":"query","required":false,"description":"1-50. Capped by the plan.","schema":{"type":"integer","minimum":1,"maximum":50},"example":20},{"name":"include_closed","in":"query","required":false,"description":"Include closed registrations.","schema":{"type":"string","enum":["true","false"],"default":"false"},"example":"false"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"query_key":{"type":"string","description":"The normalised form of `q` that was matched against the index."},"results":{"type":"array","items":{"$ref":"#/components/schemas/CorporateHit"}}},"required":["query_key","results"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"query_key":"トヨタ自動車","results":[{"corporate_number":"1180301018771","name":"トヨタ自動車株式会社","kana":"トヨタジドウシャ","kind":"株式会社","address":{"prefecture":"愛知県","city":"豊田市","street":"トヨタ町１番地","postal_code":"4710826"},"en_name":"TOYOTA MOTOR CORPORATION","closed":false,"score":1,"match":"exact_key"}]},"meta":{"dataset":{"corporate":"2026-08-31"},"sources":["出典：国税庁法人番号公表サイト（国税庁）（https://www.houjin-bangou.nta.go.jp/）を加工して作成","出典：EDINET閲覧（提出）サイト（https://disclosure2.edinet-fsa.go.jp/）のEDINETコードリスト、PDL1.0（https://disclosure2dl.edinet-fsa.go.jp/guide/static/disclosure/WZEK0030.html）を加工して作成"],"elapsed_ms":24,"plan_limits":{"max_results":50,"history":true,"resolve_candidates":10}}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/corporate/{number}":{"get":{"tags":["Corporate"],"operationId":"getCorporation","summary":"Get one company by its 13-digit corporate number","description":"Returns the full NTA record: address, English name and address, assignment/update/change dates, the reason for the last change, and closure fields. The check digit is verified before the lookup: a malformed or wrong-check-digit number is 400 `invalid_input`; a well-formed number that is not in the dataset is 200 with `data: null`. Numbers the NTA has withdrawn (duplicate assignment, or an unincorporated association that withdrew consent to publication) are removed and also return `data: null`. Companies the NTA excludes from name search are returned with `search_excluded: true`, as the NTA's own Web-API does.\n\n`history` (previous names and addresses) is empty on BASIC and populated on PRO, ULTRA and MEGA.","parameters":[{"name":"number","in":"path","required":true,"description":"13 digits, no separators.","schema":{"type":"string","pattern":"^\\d{13}$"},"example":"1180301018771"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"description":"null when nothing matched.","oneOf":[{"$ref":"#/components/schemas/CorporateDetail"},{"type":"null"}]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"corporate_number":"1180301018771","name":"トヨタ自動車株式会社","kana":"トヨタジドウシャ","kind":"株式会社","address":{"prefecture":"愛知県","city":"豊田市","street":"トヨタ町１番地","postal_code":"4710826"},"en_name":"TOYOTA MOTOR CORPORATION","closed":false,"address_outside":null,"en_address":{"prefecture":null,"city":null,"outside":null},"assignment_date":"2015-10-05","update_date":"2019-04-23","change_date":"2019-04-10","change_cause":"平成３１年４月１日東京都港区赤坂六丁目６番２０号株式会社トヨタＩＴ開発センター（9010401052572）を合併","close_date":null,"close_cause":null,"successor_corporate_number":null,"search_excluded":false,"history":[]},"meta":{"dataset":{"corporate":"2026-08-31"},"sources":["出典：国税庁法人番号公表サイト（国税庁）（https://www.houjin-bangou.nta.go.jp/）を加工して作成","出典：EDINET閲覧（提出）サイト（https://disclosure2.edinet-fsa.go.jp/）のEDINETコードリスト、PDL1.0（https://disclosure2dl.edinet-fsa.go.jp/guide/static/disclosure/WZEK0030.html）を加工して作成"],"elapsed_ms":24,"plan_limits":{"max_results":50,"history":true,"resolve_candidates":10}}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/corporate/resolve":{"post":{"tags":["Corporate"],"operationId":"resolveCorporation","summary":"Resolve a messy company name to one corporate number","description":"Entity resolution for names typed by humans or scraped from invoices: detects and strips the corporation kind (`kind_detected` / `kind_position`), normalises the rest, then ranks candidates. `resolved` is true when the top candidate scores at least 0.9 and leads the second by at least 0.15. `reasons` lists why a candidate scored: the match stage plus `prefecture` / `postal_code` when a hint agreed.\n\nCandidates: BASIC 3, paid plans up to 10.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Company name as written by the user."},"hint":{"type":"object","properties":{"prefecture":{"type":"string","enum":["北海道","青森県","岩手県","宮城県","秋田県","山形県","福島県","茨城県","栃木県","群馬県","埼玉県","千葉県","東京都","神奈川県","新潟県","富山県","石川県","福井県","山梨県","長野県","岐阜県","静岡県","愛知県","三重県","滋賀県","京都府","大阪府","兵庫県","奈良県","和歌山県","鳥取県","島根県","岡山県","広島県","山口県","徳島県","香川県","愛媛県","高知県","福岡県","佐賀県","長崎県","熊本県","大分県","宮崎県","鹿児島県","沖縄県"]},"postal_code":{"type":"string","description":"7 digits; hyphens and full-width digits are accepted."}},"additionalProperties":false},"limit":{"type":"integer","minimum":1,"maximum":10}},"required":["name"],"additionalProperties":false},"example":{"name":"トヨタ自動車（株）","hint":{"prefecture":"愛知県","postal_code":"471-0826"},"limit":5}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"normalized_name":{"type":"string"},"kind_detected":{"type":"string","nullable":true,"description":"e.g. 株式会社; null when no kind was written."},"kind_position":{"type":"string","nullable":true,"enum":["prefix","suffix",null],"description":"Where the kind appeared in the input."},"resolved":{"type":"boolean"},"candidates":{"type":"array","items":{"type":"object","properties":{"corporate_number":{"type":"string"},"name":{"type":"string"},"address":{"type":"object","properties":{"prefecture":{"type":"string","nullable":true},"city":{"type":"string","nullable":true}}},"confidence":{"type":"number","description":"0-1."},"reasons":{"type":"array","items":{"type":"string"}}}}}},"required":["normalized_name","resolved","candidates"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"normalized_name":"トヨタ自動車","kind_detected":"株式会社","kind_position":"suffix","resolved":true,"candidates":[{"corporate_number":"1180301018771","name":"トヨタ自動車株式会社","address":{"prefecture":"愛知県","city":"豊田市"},"confidence":1,"reasons":["exact_key","prefecture","postal_code"]}]},"meta":{"dataset":{"corporate":"2026-08-31"},"sources":["出典：国税庁法人番号公表サイト（国税庁）（https://www.houjin-bangou.nta.go.jp/）を加工して作成","出典：EDINET閲覧（提出）サイト（https://disclosure2.edinet-fsa.go.jp/）のEDINETコードリスト、PDL1.0（https://disclosure2dl.edinet-fsa.go.jp/guide/static/disclosure/WZEK0030.html）を加工して作成"],"elapsed_ms":24,"plan_limits":{"max_results":50,"history":true,"resolve_candidates":10}}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"payload_too_large: the request body is larger than 1 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/address/normalize":{"post":{"tags":["Address"],"operationId":"normalizeAddress","summary":"Split a Japanese address into prefecture / city / town / block / building","description":"Parses a free-form Japanese address against the Japan Post town dictionary. Handles a missing prefecture (`prefecture_inferred`), designated-city wards (`横浜市中区` stays one `city`), 丁目/番地/号 written in kanji, full-width digits or hyphens, building and room suffixes, and Kyoto street names (`kyoto_street_name`). `level` says how deep the parse got (`none`, `prefecture`, `city`, `town`, `chome`, `banchi`, `go`) and `postal_codes` lists every 7-digit code that matches the part that was understood.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","minLength":1,"maxLength":200}},"required":["address"],"additionalProperties":false},"example":{"address":"東京都港区芝公園4-2-8"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"normalized":{"type":"string"},"components":{"$ref":"#/components/schemas/AddressComponents"},"postal_codes":{"type":"array","items":{"type":"string"}},"level":{"type":"string","enum":["none","prefecture","city","town","chome","banchi","go"]},"issues":{"$ref":"#/components/schemas/AddressIssues"}},"required":["normalized","components","postal_codes","level","issues"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"normalized":"東京都港区芝公園4-2-8","components":{"prefecture":"東京都","city":"港区","town":"芝公園","chome":"4","banchi":"2","go":"8","building":null,"room":null,"street_note":null},"postal_codes":["1050011"],"level":"go","issues":[]},"meta":{"dataset":{"postal":"2026-08-31"},"sources":["郵便番号データ：日本郵便株式会社（https://www.post.japanpost.jp/zipcode/）"],"elapsed_ms":6}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"payload_too_large: the request body is larger than 1 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/postal/{zip}":{"get":{"tags":["Postal"],"operationId":"getPostalCode","summary":"Look up a 7-digit postal code (kanji, kana and roman)","description":"Accepts full-width digits and any separator (`１０５－００１１`, `105-0011`, `105 0011`). Returns every row Japan Post publishes for the code: `kind: general` town rows (with kana and roman) and `kind: office` large-volume recipient rows (with `office_name`). Parenthetical notes Japan Post stores inside the town name (e.g. 次のビルを除く) are moved to `town_note`. An unknown but well-formed code is 200 with an empty list.","parameters":[{"name":"zip","in":"path","required":true,"description":"7 digits; separators and full-width digits accepted.","schema":{"type":"string"},"example":"1050011"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"postal_code":{"type":"string"},"entries":{"type":"array","items":{"$ref":"#/components/schemas/PostalEntry"}}},"required":["postal_code","entries"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"postal_code":"1050011","entries":[{"postal_code":"1050011","prefecture":"東京都","city":"港区","town":"芝公園","town_note":null,"kana":{"prefecture":"トウキョウト","city":"ミナトク","town":"シバコウエン"},"roman":{"prefecture":"TOKYO TO","city":"MINATO KU","town":"SHIBAKOEN","generated":false},"jis_code":"13103","kind":"general"}]},"meta":{"dataset":{"postal":"2026-08-31"},"sources":["郵便番号データ：日本郵便株式会社（https://www.post.japanpost.jp/zipcode/）"],"elapsed_ms":6}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/postal/search":{"get":{"tags":["Postal"],"operationId":"searchPostalCodes","summary":"Find postal codes from a partial address","description":"Parses the address the same way as `/v1/address/normalize` and returns the postal rows for the town it resolved to (or every town under the city when only a partial town was given). Every entry carries its own `postal_code`, so a multi-code result needs no second call. `issues` carries the same parse warnings as `/v1/address/normalize`.\n\nBASIC returns at most 5 results (paid plans default to 20, `limit` up to 50); `meta.plan_limits` echoes the caps in force.","parameters":[{"name":"address","in":"query","required":true,"description":"Any part of an address, from `東京都港区` to a full street address.","schema":{"type":"string","minLength":1,"maxLength":200},"example":"東京都港区芝公園4-2-8"},{"name":"limit","in":"query","required":false,"description":"1-50. Capped by the plan.","schema":{"type":"integer","minimum":1,"maximum":50},"example":20}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/PostalEntry"}},"issues":{"$ref":"#/components/schemas/AddressIssues"}},"required":["entries","issues"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"entries":[{"postal_code":"1050011","prefecture":"東京都","city":"港区","town":"芝公園","town_note":null,"kana":{"prefecture":"トウキョウト","city":"ミナトク","town":"シバコウエン"},"roman":{"prefecture":"TOKYO TO","city":"MINATO KU","town":"SHIBAKOEN","generated":false},"jis_code":"13103","kind":"general"}],"issues":[]},"meta":{"dataset":{"postal":"2026-08-31"},"sources":["郵便番号データ：日本郵便株式会社（https://www.post.japanpost.jp/zipcode/）"],"elapsed_ms":6,"plan_limits":{"max_results":50,"history":true,"resolve_candidates":10}}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/address/romanize":{"post":{"tags":["Address"],"operationId":"romanizeAddress","summary":"Turn a Japanese address into a Western-order English address","description":"Reverses the order and romanises each part using the Japan Post roman table, falling back to a morphological reading for building names. `lines` is the same address split for a postal label; `roman` is the one-line form. Room and floor suffixes become `#301` / `3F`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","minLength":1,"maxLength":200}},"required":["address"],"additionalProperties":false},"example":{"address":"東京都港区芝公園4-2-8 東京タワー"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"roman":{"type":"string"},"lines":{"type":"array","items":{"type":"string"}},"components":{"$ref":"#/components/schemas/AddressComponents"},"issues":{"$ref":"#/components/schemas/AddressIssues"}},"required":["roman","lines","components","issues"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"roman":"Tokyo Tower, 4-2-8 Shibakoen, Minato-ku, Tokyo 105-0011, Japan","lines":["Tokyo Tower","4-2-8 Shibakoen","Minato-ku, Tokyo 105-0011","Japan"],"components":{"prefecture":"東京都","city":"港区","town":"芝公園","chome":"4","banchi":"2","go":"8","building":"東京タワー","room":null,"street_note":null},"issues":[]},"meta":{"dataset":{"postal":"2026-08-31"},"sources":["郵便番号データ：日本郵便株式会社（https://www.post.japanpost.jp/zipcode/）","形態素解析：Lindera（MIT）+ IPADIC（BSD 風ライセンス、奈良先端科学技術大学院大学）"],"elapsed_ms":5}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"payload_too_large: the request body is larger than 1 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/text/furigana":{"post":{"tags":["Text"],"operationId":"getFurigana","summary":"Read Japanese text as kana, with okurigana-aware ruby pairs","description":"Morphological analysis (Lindera + IPADIC) runs inside the worker, so the call is synchronous and deterministic. `reading` is the whole text read in the `output` script; `tokens` keeps the per-word breakdown with the IPADIC part of speech, subcategories joined with `-` (`名詞-固有名詞-人名-姓`, `動詞-自立`, ...). A word the dictionary does not know gets `pos: 未知語` and its surface form as the `reading`. `ruby: true` adds the `ruby` array, in which only the kanji part carries the reading (働く -> 働/はたら + く) and neighbouring runs that need no reading are merged into one `ruby: null` pair; the field is omitted when `ruby` is false. Half-width katakana is widened before the analysis. An unknown key in the body is 400.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":2000},"output":{"type":"string","enum":["hiragana","katakana"],"default":"hiragana"},"ruby":{"type":"boolean","default":false}},"required":["text"],"additionalProperties":false},"example":{"text":"渡辺さんは東京都で働く","output":"hiragana","ruby":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"reading":{"type":"string"},"tokens":{"type":"array","items":{"type":"object","properties":{"surface":{"type":"string"},"reading":{"type":"string","description":"In the `output` script; equal to `surface` for an unknown word."},"pos":{"type":"string","description":"IPADIC part of speech; 未知語 for an unknown word."}},"required":["surface","reading","pos"]}},"ruby":{"type":"array","items":{"type":"object","properties":{"base":{"type":"string"},"ruby":{"type":"string","nullable":true,"description":"null for a run that carries no reading (kana, punctuation, okurigana)."}},"required":["base","ruby"]},"description":"Only present when `ruby: true` was sent."}},"required":["reading","tokens"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"reading":"わたなべさんはとうきょうとではたらく","tokens":[{"surface":"渡辺","reading":"わたなべ","pos":"名詞-固有名詞-人名-姓"},{"surface":"さん","reading":"さん","pos":"名詞-接尾-人名"},{"surface":"は","reading":"は","pos":"助詞-係助詞"},{"surface":"東京","reading":"とうきょう","pos":"名詞-固有名詞-地域-一般"},{"surface":"都","reading":"と","pos":"名詞-接尾-地域"},{"surface":"で","reading":"で","pos":"助詞-格助詞-一般"},{"surface":"働く","reading":"はたらく","pos":"動詞-自立"}],"ruby":[{"base":"渡辺","ruby":"わたなべ"},{"base":"さんは","ruby":null},{"base":"東京","ruby":"とうきょう"},{"base":"都","ruby":"と"},{"base":"で","ruby":null},{"base":"働","ruby":"はたら"},{"base":"く","ruby":null}]},"meta":{"dataset":{},"sources":["形態素解析：Lindera（MIT）+ IPADIC（BSD 風ライセンス、奈良先端科学技術大学院大学）"],"elapsed_ms":12}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"payload_too_large: the request body is larger than 1 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/text/romaji":{"post":{"tags":["Text"],"operationId":"toRomaji","summary":"Romanise Japanese text (Hepburn, Kunrei or passport style)","description":"The text is read morphologically first, so kanji is romanised too. `system` picks the table: `hepburn` (shi / chi / tsu / fu, ん before b/m/p as m, ん before a vowel or y as n'), `kunrei` (si / ti / tu / hu; ん is n before a consonant and n' before a vowel or y, never m: しんばし -> `sinbasi`, かんい -> `kan'i`, しんや -> `sin'ya`) or `passport`, which is Hepburn as Japanese passports write it (plain n instead of n', and long vowels always dropped). `long_vowel` says how 長音 is written: `none` keeps the spelling (おおの -> `oono`) except under `passport`, which shortens it anyway (`ono`, さとう -> `sato`); `macron` writes `oo`/`ou` as `ō`, `uu` as `ū`, `aa` as `ā` and `ee` as `ē` (`ii` and `ei` are left alone: にいがた -> `niigata`, えいご -> `eigo`); `oh` writes `oo` as `oh` (おおの -> `ohno`) and shortens the rest. `case` has no fixed default: it is `upper` when `system` is `passport` and `title` otherwise. Tokens are joined with single spaces (a space before 、。,.!? is removed) and a non-kana symbol token is passed through unchanged. An unknown key in the body is 400.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":2000},"system":{"type":"string","enum":["hepburn","kunrei","passport"],"default":"hepburn"},"long_vowel":{"type":"string","enum":["none","macron","oh"],"default":"none"},"case":{"type":"string","enum":["lower","upper","title"],"description":"Defaults to upper for system=passport, title otherwise."}},"required":["text"],"additionalProperties":false},"example":{"text":"渡辺翔太","system":"hepburn","long_vowel":"macron","case":"title"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"romaji":{"type":"string"},"tokens":{"type":"array","items":{"type":"object","properties":{"surface":{"type":"string"},"reading":{"type":"string","description":"Katakana, whatever the options; equal to `surface` for an unknown word."},"romaji":{"type":"string"}},"required":["surface","reading","romaji"]}}},"required":["romaji","tokens"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"romaji":"Watanabe Shōta","tokens":[{"surface":"渡辺","reading":"ワタナベ","romaji":"Watanabe"},{"surface":"翔太","reading":"ショウタ","romaji":"Shōta"}]},"meta":{"dataset":{},"sources":["形態素解析：Lindera（MIT）+ IPADIC（BSD 風ライセンス、奈良先端科学技術大学院大学）"],"elapsed_ms":5}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"payload_too_large: the request body is larger than 1 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/text/kana":{"post":{"tags":["Text"],"operationId":"convertKana","summary":"Convert between hiragana, katakana and half-width katakana","description":"Without `reading` only kana is converted and kanji, digits and Latin letters are left alone (half-width katakana is widened first, so `ｼｮｳﾀ` -> `ショウタ`). With `reading: true` the text is read morphologically first, so kanji becomes kana too — the result is then the concatenation of the token readings, which drops the whitespace. `meta.sources` names Lindera only when `reading: true`. An unknown key in the body is 400.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":2000},"to":{"type":"string","enum":["hiragana","katakana","halfwidth_katakana"]},"reading":{"type":"boolean","default":false}},"required":["text","to"],"additionalProperties":false},"example":{"text":"渡辺翔太","to":"hiragana","reading":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"text":"わたなべしょうた"},"meta":{"dataset":{},"sources":["形態素解析：Lindera（MIT）+ IPADIC（BSD 風ライセンス、奈良先端科学技術大学院大学）"],"elapsed_ms":3}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"payload_too_large: the request body is larger than 1 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/text/normalize":{"post":{"tags":["Text"],"operationId":"normalizeText","summary":"Normalise Japanese text and report every change that was made","description":"Old glyphs to new (髙 -> 高), compatibility characters (㈱ -> (株), ① -> (1)), combining dakuten (か + ゛ -> が), width, whitespace and dashes. Every substitution is reported in `changes` with the rule that caused it, so you can show a diff or audit the transformation. The rules run in a fixed order — `compat_chars`, `combine_dakuten`, `width`, `nfkc` (everything the width, space and dakuten steps did not claim), `kyujitai`, `space`, `dash` — and `changes` is in that order. A `changes` entry is one contiguous run that the rule changed, except `space` and `dash`, which work on the whole string and therefore report the whole string before and after. `options` is a partial object: unknown keys or values are 400.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":2000},"options":{"type":"object","properties":{"width":{"type":"string","enum":["narrow_alnum_wide_kana","narrow_all","wide_all","none"],"default":"narrow_alnum_wide_kana","description":"narrow_alnum_wide_kana: ASCII to half width, half-width kana to full width."},"kyujitai":{"type":"boolean","default":true},"compat_chars":{"type":"boolean","default":true},"combine_dakuten":{"type":"boolean","default":true},"space":{"type":"string","enum":["single","none","keep"],"default":"single","description":"single also trims the ends."},"dash":{"type":"string","enum":["ascii","keep"],"default":"ascii"},"circled_numbers":{"type":"string","enum":["paren","plain"],"default":"paren","description":"① -> (1) or 1. Applies only when compat_chars is on."}},"additionalProperties":false}},"required":["text"],"additionalProperties":false},"example":{"text":"㈱髙島屋　１２３－４５６７ ｶﾞ"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"text":{"type":"string"},"changes":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"rule":{"type":"string","enum":["compat_chars","combine_dakuten","width","nfkc","kyujitai","space","dash"]}},"required":["from","to","rule"]}}},"required":["text","changes"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"text":"(株)高島屋 123-4567 ガ","changes":[{"from":"㈱","to":"(株)","rule":"compat_chars"},{"from":"１２３－４５６７","to":"123-4567","rule":"width"},{"from":"ｶﾞ","to":"ガ","rule":"width"},{"from":"髙","to":"高","rule":"kyujitai"},{"from":"(株)高島屋　123-4567 ガ","to":"(株)高島屋 123-4567 ガ","rule":"space"}]},"meta":{"dataset":{},"sources":[],"elapsed_ms":2}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"payload_too_large: the request body is larger than 1 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/name/reading":{"post":{"tags":["Name"],"operationId":"readPersonName","summary":"Split a Japanese personal name and read it","description":"Splits 姓 and 名 and ranks the readings against a name dictionary built from JMnedict plus surname frequencies counted in the NTA corporate corpus. With `split: auto` (the default) send `name`: a name written with a space is split on the space; otherwise the split is decided by a TypeScript port of NameDivider's GBDT model (kanji position statistics, a 40,000-surname ranking and 268 gradient-boosted trees; the author reports 99.9% on real names), and `split_confidence` is the winning split's softmax share. Two guards run first: an input with no kanji is not split (`reasons: [\"no_kanji\"]`), and an input that is itself a known surname (in the ranking, or in the dictionary) is returned whole with `given: null` (`reasons: [\"surname_only\"]`), so sending just `小林` or `東海林` works. `split_confidence` is null whenever the name was not split, and when the split was given rather than inferred. All-kana names such as `さとうはなこ` therefore come back whole. With `split: provided` send `family` (required) and optionally `given` instead; `name` is then rejected. Omitting `given` there returns `given: null` with `given_readings: []` and `full_readings: []` — only the 姓 is read. Each side's readings sum to 1. `reasons` carries `fallback_morph` when a part was not in the dictionary at all and the morphological reading was used (confidence 0.3), and `lindera_tiebreak` when equally frequent readings were reordered to put the morphological reading first (which is how 東海林 becomes しょうじ). It also carries `namedivider_rule` when the split came from the 2-character (1+1) or kanji/kana-boundary rule, `namedivider_gbdt` when the GBDT model picked the split, and `too_short` for a 1-character input with no dictionary or ranking match, returned whole. `full_readings` combines the top three of each side, sorted by the product of their confidences; `romaji` is the passport style, which is what Japanese passports and airline bookings use. This is the one endpoint that needs the `names` dataset, so it answers 503 `dataset_unavailable` until that dataset has been imported.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":20,"description":"Full name, with or without a space. Required when split is auto; rejected when split is provided."},"split":{"type":"string","enum":["auto","provided"],"default":"auto"},"family":{"type":"string","minLength":1,"maxLength":10,"description":"Only with split=provided, where it is required."},"given":{"type":"string","minLength":1,"maxLength":10,"description":"Only with split=provided, where it is optional."}},"additionalProperties":false},"example":{"name":"渡辺翔太","split":"auto"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"family":{"type":"string","nullable":true,"description":"Never null in practice: an unsplittable input returns the whole string here."},"given":{"type":"string","nullable":true,"description":"null when the name was not split."},"split_confidence":{"type":"number","nullable":true,"description":"0-1. null when the name was not split (no kanji, a known surname, or a single character) or the split was given; 1 for the two rule-based splits (2 characters; kanji/kana boundary); otherwise the winning split's softmax share over the n-1 candidate cut points, so it is bounded by roughly 0.73 for 3 characters, 0.58 for 4, 0.48 for 5 and lower for longer names even when the split is certain — compare it with the runner-up, not against an absolute threshold."},"family_readings":{"type":"array","items":{"$ref":"#/components/schemas/Reading"}},"given_readings":{"type":"array","items":{"$ref":"#/components/schemas/Reading"}},"full_readings":{"type":"array","items":{"type":"object","properties":{"hiragana":{"type":"string","description":"Family and given separated by a space."},"romaji":{"type":"string"},"confidence":{"type":"number"}},"required":["hiragana","romaji","confidence"]}},"reasons":{"type":"array","items":{"type":"string","enum":["no_kanji","surname_only","too_short","namedivider_rule","namedivider_gbdt","fallback_morph","lindera_tiebreak"]}}},"required":["family","given","split_confidence","family_readings","given_readings","full_readings","reasons"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"family":"渡辺","given":"翔太","split_confidence":0.576,"family_readings":[{"hiragana":"わたなべ","confidence":0.893},{"hiragana":"わたべ","confidence":0.018}],"given_readings":[{"hiragana":"しょうた","confidence":1}],"full_readings":[{"hiragana":"わたなべ しょうた","romaji":"Watanabe Shota","confidence":0.893},{"hiragana":"わたべ しょうた","romaji":"Watabe Shota","confidence":0.018}],"reasons":["namedivider_gbdt"]},"meta":{"dataset":{"names":"2026-08-31"},"sources":["JMnedict © EDRDG, CC BY-SA 3.0（https://www.edrdg.org/）","姓名分割：NameDivider（MIT、https://github.com/rskmoi/namedivider-python）と名字由来net の姓データ"],"elapsed_ms":7}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"payload_too_large: the request body is larger than 1 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/calendar/holidays":{"get":{"tags":["Calendar"],"operationId":"listHolidays","summary":"List Japanese public holidays for a year or a date range","description":"Up to the last year the Cabinet Office has published, the list is the official CSV verbatim (`source: cao_csv`). Beyond it the dates are computed from the Holidays Act, including the equinoxes, Happy-Monday rules, substitute holidays (振替休日) and citizens' holidays (国民の休日) (`source: rule`; `mixed` when a range spans both). Pass `year`, or `from` and `to` (range up to 3 years).","parameters":[{"name":"year","in":"query","required":false,"description":"1955-2099.","schema":{"type":"integer","minimum":1955,"maximum":2099},"example":2026},{"name":"from","in":"query","required":false,"description":"Start date, inclusive. Use with `to` instead of `year`.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"YYYY-MM-DD"},"example":"2026-04-01"},{"name":"to","in":"query","required":false,"description":"End date, inclusive. At most 3 years after `from`.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"YYYY-MM-DD"},"example":"2027-03-31"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"holidays":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"name":{"type":"string","description":"Japanese name, e.g. 元日."},"kind":{"type":"string","enum":["national","substitute","citizens"]}},"required":["date","name","kind"]}},"source":{"type":"string","enum":["cao_csv","rule","mixed"]}},"required":["holidays","source"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"holidays":[{"date":"2026-01-01","name":"元日","kind":"national"},{"date":"2026-01-12","name":"成人の日","kind":"national"},{"date":"2026-02-11","name":"建国記念の日","kind":"national"}],"source":"cao_csv"},"meta":{"dataset":{"holidays":"2026-02-01"},"sources":["出典：内閣府「国民の祝日について」（https://www8.cao.go.jp/chosei/shukujitsu/gaiyou.html）"],"elapsed_ms":4}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/calendar/business-days":{"post":{"tags":["Calendar"],"operationId":"calculateBusinessDays","summary":"Add, subtract or count Japanese business days","description":"`op` selects the calculation: `add` / `subtract` (needs `date` and `days`), `count` (needs `from` and `to`, at most 366 days), `is_business_day`, `next`, `previous` (need `date`). Weekends and public holidays are skipped by default, and so is the 12-29..01-03 year-end shutdown (`options.year_end`, which is what Japanese companies actually observe). `options.extra_holidays` adds company holidays, `options.extra_workdays` forces a day to count. Every skipped day is returned with the reason it was skipped.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"op":{"type":"string","enum":["add","subtract","count","is_business_day","next","previous"]},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Required for add, subtract, is_business_day, next and previous."},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Required for count."},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Required for count."},"days":{"type":"integer","minimum":-366,"maximum":366,"description":"Required for add and subtract."},"options":{"$ref":"#/components/schemas/BusinessOptions"}},"required":["op"],"additionalProperties":false},"example":{"op":"add","date":"2026-12-28","days":3,"options":{"extra_holidays":["2027-01-04"]}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"result":{"type":"string","description":"add / subtract / next / previous."},"count":{"type":"integer","description":"count."},"business_day":{"type":"boolean","description":"is_business_day."},"reason":{"type":"string","enum":["holiday","year_end","weekend","extra_holiday"],"description":"is_business_day, when the answer is false."},"skipped":{"$ref":"#/components/schemas/SkippedDays"}}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"result":"2027-01-07","skipped":[{"date":"2026-12-29","reason":"year_end"},{"date":"2026-12-30","reason":"year_end"},{"date":"2026-12-31","reason":"year_end"},{"date":"2027-01-01","reason":"holiday"},{"date":"2027-01-02","reason":"year_end"},{"date":"2027-01-03","reason":"year_end"},{"date":"2027-01-04","reason":"extra_holiday"}]},"meta":{"dataset":{"holidays":"2026-02-01"},"sources":["出典：内閣府「国民の祝日について」（https://www8.cao.go.jp/chosei/shukujitsu/gaiyou.html）"],"elapsed_ms":5}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"payload_too_large: the request body is larger than 1 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/calendar/wareki":{"get":{"tags":["Calendar"],"operationId":"convertWareki","summary":"Convert between the Gregorian calendar and Japanese era years (和暦)","description":"Pass `date` to get the era form, or `wareki` to get back a Gregorian date. Era boundaries are exact to the day (2019-04-30 is 平成31年, 2019-05-01 is 令和元年), the first year of an era is written 元年, and both kanji (`令和8年9月6日`) and short (`R8.9.6`) forms are accepted, with full-width digits. Dates before 1873-01-01 (when Japan adopted the Gregorian calendar) are rejected with 400.","parameters":[{"name":"date","in":"query","required":false,"description":"Gregorian date, 1873-01-01 or later.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"YYYY-MM-DD"},"example":"2026-09-06"},{"name":"wareki","in":"query","required":false,"description":"Era date, e.g. 令和8年9月6日 or R8.9.6. Use instead of `date`.","schema":{"type":"string"},"example":"令和8年9月6日"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"era":{"type":"string","description":"明治 / 大正 / 昭和 / 平成 / 令和. Present when `date` was given."},"era_en":{"type":"string","description":"Meiji / Taisho / Showa / Heisei / Reiwa."},"year":{"type":"integer"},"month":{"type":"integer"},"day":{"type":"integer"},"text":{"type":"string","description":"e.g. 令和8年9月6日 (元年 for year 1)."},"short":{"type":"string","description":"e.g. R8.9.6."},"date":{"type":"string","description":"Gregorian date. Present when `wareki` was given."}}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"era":"令和","era_en":"Reiwa","year":8,"month":9,"day":6,"text":"令和8年9月6日","short":"R8.9.6"},"meta":{"dataset":{},"sources":[],"elapsed_ms":2}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/validate/phone":{"post":{"tags":["Validate"],"operationId":"validatePhone","summary":"Validate and classify a Japanese phone number","description":"Normalises full-width digits, `+81` and `0081` and strips every separator (spaces, hyphens, dots, brackets, a `tel:` prefix), then classifies by prefix and digit count: `landline` (10 digits, with the area code and its region from the MIC list in `area`), `mobile` (070/080/090), `toll_free` (0120/0800), `navi_dial` (0570), `ip` (050) or `m2m` (020). Returns the national format with hyphens and the E.164 form. A number that is not a well-formed Japanese one — wrong digit count, a foreign `+1 ...` number, letters only — is **200** with `valid: false`, `type: unknown` and nulls; only an empty or over-long `phone` field is 400. `area` is null for every non-geographic type and for a landline whose area code is not in the MIC table (such a number is then formatted 4-2-4). The longest matching area code wins, falling back to shorter ones.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"type":"string","minLength":1,"maxLength":32}},"required":["phone"],"additionalProperties":false},"example":{"phone":"03-1234-5678"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"valid":{"type":"boolean"},"type":{"type":"string","enum":["landline","mobile","toll_free","navi_dial","ip","m2m","unknown"]},"area":{"type":"object","properties":{"code":{"type":"string"},"region":{"type":"string","description":"Japanese place name from the MIC area-code list, e.g. 東京."}},"required":["code","region"],"nullable":true,"description":"null unless the number is a landline with a known area code."},"national":{"type":"string","nullable":true,"description":"Hyphenated national format; null when invalid."},"e164":{"type":"string","nullable":true,"description":"+81 form; null when invalid."}},"required":["valid","type","area","national","e164"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"valid":true,"type":"landline","area":{"code":"03","region":"東京"},"national":"03-1234-5678","e164":"+81312345678"},"meta":{"dataset":{},"sources":[],"elapsed_ms":2}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"payload_too_large: the request body is larger than 1 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/validate/postal-code":{"post":{"tags":["Validate"],"operationId":"validatePostalCode","summary":"Validate a postal code and optionally check that it exists","description":"Format check only by default, and it is strict: an optional 〒, surrounding spaces and one separator between the 3rd and 4th digit are allowed (`1050011`, `105-0011`, `105 0011`, `〒105-0011`, `１０５－００１１`), and anything else fails. Junk that merely happens to contain seven digits (`1050011abc`, `10-5-0011`) is `valid: false`, unlike the lenient parsing `GET /v1/postal/{zip}` does on its path segment. A code that fails the check is **200** with `valid: false` and `normalized: null`, not a 400 — only an empty or over-long `postal_code` field is 400. With `check_existence: true` the code is also looked up in the Japan Post dataset (town rows and large-volume recipient rows) and `exists` is added; it is false for a code that is well-formed but unused, and false for an invalid one. The `exists` field is absent when `check_existence` is not set, and `meta.sources` carries the Japan Post attribution only when it is.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"postal_code":{"type":"string","minLength":1,"maxLength":16},"check_existence":{"type":"boolean","default":false}},"required":["postal_code"],"additionalProperties":false},"example":{"postal_code":"１０５－００１１","check_existence":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"valid":{"type":"boolean"},"normalized":{"type":"string","nullable":true,"description":"7 digits, no separators; null when invalid."},"exists":{"type":"boolean","description":"Only present when check_existence was true."}},"required":["valid","normalized"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"valid":true,"normalized":"1050011","exists":true},"meta":{"dataset":{},"sources":["郵便番号データ：日本郵便株式会社（https://www.post.japanpost.jp/zipcode/）"],"elapsed_ms":7}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"payload_too_large: the request body is larger than 1 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/validate/corporate-number":{"post":{"tags":["Validate"],"operationId":"validateCorporateNumber","summary":"Validate a corporate number check digit and optionally check that it exists","description":"Verifies the check digit with the NTA formula (the leading digit against the other 12). A wrong check digit is a **200** with `valid: false` and `check_digit_ok: false`, because this is a validation endpoint — unlike `GET /v1/corporate/{number}`, which rejects it with 400. Only an input that is not exactly 13 digits is 400 here. With `check_existence: true` the number is also looked up in the NTA dataset and `exists` is added; a number that passes the check digit but was never assigned is `exists: false`. `valid` mirrors `check_digit_ok` — it never takes `exists` into account.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"corporate_number":{"type":"string","pattern":"^\\d{13}$"},"check_existence":{"type":"boolean","default":false}},"required":["corporate_number"],"additionalProperties":false},"example":{"corporate_number":"1180301018771","check_existence":true}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"valid":{"type":"boolean"},"check_digit_ok":{"type":"boolean"},"exists":{"type":"boolean","description":"Only present when check_existence was true."}},"required":["valid","check_digit_ok"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"valid":true,"check_digit_ok":true,"exists":true},"meta":{"dataset":{},"sources":["出典：国税庁法人番号公表サイト（国税庁）（https://www.houjin-bangou.nta.go.jp/）を加工して作成"],"elapsed_ms":5}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"payload_too_large: the request body is larger than 1 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/batch":{"post":{"tags":["Batch"],"operationId":"batch","summary":"Run up to 100 calls in one request (MEGA only)","description":"Each item carries your own `id`, an `endpoint` (any other `/v1/...` path, query string included) and, for POST endpoints, a `body`. **The presence of `body` chooses the method**: an item with `body` is dispatched as POST, an item without it as GET. The outer HTTP status is always 200: each item reports its own `status`, with `data` when it succeeded and `error` (the inner `error` object, not a whole envelope) when it did not — an unknown path is that item's 404 — and one failing item never affects the others. `/v1/batch` itself, a path outside `/v1/`, a `..` traversal and a URL fragment are rejected up front — that is 400 for the whole request, not a failed item. One call counts as one Request in RapidAPI's Analytics (it is also recorded as a single usage row with the item count). `meta` describes the batch call itself; per-item `meta` is not returned.\n\nMEGA only; BASIC, PRO and ULTRA get 403 `plan_required` (the plan is checked before the body is read, so an oversized body on those plans is still 403). 1-100 items; the request body must be 1 MB or smaller (413 `payload_too_large`).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"requests":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":64,"description":"Your own id, echoed back on the matching result."},"endpoint":{"type":"string","minLength":4,"maxLength":512,"description":"A /v1/ path other than /v1/batch, e.g. /v1/postal/1050011 or /v1/calendar/wareki?date=2026-09-06."},"body":{"type":"object","properties":{},"description":"Send it for POST endpoints. Omitting it makes the item a GET."}},"required":["id","endpoint"],"additionalProperties":false}}},"required":["requests"],"additionalProperties":false},"example":{"requests":[{"id":"1","endpoint":"/v1/postal/1050011"},{"id":"2","endpoint":"/v1/address/normalize","body":{"address":"東京都港区芝公園4-2-8"}}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"integer","description":"The HTTP status the endpoint would have returned on its own."},"data":{"type":"object","properties":{},"description":"The `data` of the inner response. Present when `status` is 200."},"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["id","status"]}}},"required":["results"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"results":[{"id":"1","status":200,"data":{"postal_code":"1050011","entries":[{"postal_code":"1050011","prefecture":"東京都","city":"港区","town":"芝公園","town_note":null,"kana":{"prefecture":"トウキョウト","city":"ミナトク","town":"シバコウエン"},"roman":{"prefecture":"TOKYO TO","city":"MINATO KU","town":"SHIBAKOEN","generated":false},"jis_code":"13103","kind":"general"}]}},{"id":"2","status":200,"data":{"normalized":"東京都港区芝公園4-2-8","components":{"prefecture":"東京都","city":"港区","town":"芝公園","chome":"4","banchi":"2","go":"8","building":null,"room":null,"street_note":null},"postal_codes":["1050011"],"level":"go","issues":[]}}]},"meta":{"dataset":{},"sources":[],"elapsed_ms":12}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"payload_too_large: the request body is larger than 1 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/health":{"get":{"tags":["Meta"],"operationId":"health","summary":"Health check","description":"The only endpoint besides `/v1/openapi.json` that needs no authentication.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"service":{"type":"string"},"time":{"type":"string","format":"date-time"}},"required":["service","time"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"service":"rapid-jp-api","time":"2026-09-16T02:37:48.597Z"},"meta":{"dataset":{},"sources":[],"elapsed_ms":0}}}}}}}},"/v1/datasets":{"get":{"tags":["Meta"],"operationId":"listDatasets","summary":"Dataset versions currently served","description":"`as_of` is the publication date of the full dataset currently served (corporate: the NTA monthly file). `updated_through` is the date the data is current through: for corporate it advances every day as the NTA diff is applied, for the others it equals `as_of`. `meta.dataset` on every response carries the same `updated_through` value, so quote that when you show the data. `active_gen` increments on every full import and `switched_at` is when the new generation went live (imports are swapped in without downtime).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"datasets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["corporate","postal","holidays","names"]},"as_of":{"type":"string","nullable":true,"description":"YYYY-MM-DD; null before the first import."},"updated_through":{"type":"string","nullable":true,"description":"YYYY-MM-DD; the date the data is current through (corporate: last daily diff applied). Null before the first import."},"active_gen":{"type":"integer","description":"0 before the first import."},"row_count":{"type":"integer"},"switched_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["name","as_of","updated_through","active_gen","row_count","switched_at"]}}},"required":["datasets"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"datasets":[{"name":"corporate","as_of":"2026-08-31","updated_through":"2026-09-16","active_gen":3,"row_count":5312884,"switched_at":"2026-09-01T02:14:07.918Z"},{"name":"postal","as_of":"2026-08-31","updated_through":"2026-08-31","active_gen":2,"row_count":124512,"switched_at":"2026-09-01T02:20:31.402Z"},{"name":"holidays","as_of":"2026-02-01","updated_through":"2026-02-01","active_gen":1,"row_count":1068,"switched_at":"2026-09-01T02:20:44.115Z"},{"name":"names","as_of":"2026-08-31","updated_through":"2026-08-31","active_gen":1,"row_count":241033,"switched_at":"2026-09-01T02:21:02.660Z"}]},"meta":{"dataset":{},"sources":[],"elapsed_ms":3}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/account":{"get":{"tags":["Meta"],"operationId":"getAccount","summary":"Your plan and the limits that apply to it","description":"Echoes the plan RapidAPI reports for your key and the caps enforced for it, so a client can adapt without hard-coding plan names.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"plan":{"type":"string","enum":["BASIC","PRO","ULTRA","MEGA"]},"limits":{"$ref":"#/components/schemas/PlanLimits"},"monthly_requests":{"type":"integer","description":"Requests included in the plan."},"free_tier":{"type":"object","properties":{"monthly_requests_per_cluster":{"type":"integer","description":"Free accounts that share one network share this monthly budget."},"daily_requests_all_basic":{"type":"integer","description":"Daily ceiling for the whole free tier."}}}},"required":["plan","limits","monthly_requests","free_tier"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["ok","data","meta"]},"example":{"ok":true,"data":{"plan":"PRO","limits":{"search_max_results":50,"search_default":20,"resolve_max_candidates":10,"history":true,"batch":false,"batch_max_items":0},"monthly_requests":20000,"free_tier":{"monthly_requests_per_cluster":500,"daily_requests_all_basic":20000}},"meta":{"dataset":{},"sources":[],"elapsed_ms":2}}}}},"400":{"description":"invalid_input: a parameter or body field is missing or out of range. `error.field` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: the request did not come through the RapidAPI gateway, or X-RapidAPI-User was missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"plan_required (the endpoint or option needs a higher plan) or blocked (the account is blocked; contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"free_tier_busy (the whole free tier hit its daily ceiling; retry after 00:00 UTC) or free_tier_shared_limit (free accounts sharing one network used up the monthly budget). Both send Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"dataset_unavailable: the dataset this endpoint needs has no active generation yet (only right after a fresh deployment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"CorporateHit":{"type":"object","properties":{"corporate_number":{"type":"string","description":"13 digits.","example":"1180301018771"},"name":{"type":"string"},"kana":{"type":"string","nullable":true,"description":"Katakana reading as published by the NTA."},"kind":{"type":"string","description":"Corporation kind, in Japanese (株式会社, 有限会社, 合同会社, 国の機関, 地方公共団体, 外国会社等, ...)."},"address":{"$ref":"#/components/schemas/CorporateAddress"},"en_name":{"type":"string","nullable":true,"description":"English name: as registered with the NTA (about 15,000 companies), or from the FSA's EDINET code list for filers such as listed companies (about 4,300). null otherwise."},"closed":{"type":"boolean","description":"true when the registration is closed (merged, dissolved, ...)."},"score":{"type":"number","description":"0-1; the list is sorted by it."},"match":{"type":"string","enum":["exact_key","prefix","kana","en","fts"]}},"required":["corporate_number","name","kind","address","closed","score","match"]},"Meta":{"type":"object","properties":{"dataset":{"type":"object","properties":{"corporate":{"type":"string","nullable":true,"description":"As-of date (YYYY-MM-DD) of the corporate dataset used."},"postal":{"type":"string","nullable":true},"holidays":{"type":"string","nullable":true},"names":{"type":"string","nullable":true}}},"sources":{"type":"array","items":{"type":"string","description":"Attribution strings for the data actually touched by this call. Display them when you show the data."}},"elapsed_ms":{"type":"integer","description":"Server-side processing time."},"plan_limits":{"type":"object","properties":{"max_results":{"type":"integer"},"history":{"type":"boolean"},"resolve_candidates":{"type":"integer"}}}},"required":["dataset","sources","elapsed_ms"]},"Error":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"$ref":"#/components/schemas/ErrorDetail"}},"required":["ok","error"]},"CorporateDetail":{"type":"object","properties":{"corporate_number":{"type":"string","description":"13 digits.","example":"1180301018771"},"name":{"type":"string"},"kana":{"type":"string","nullable":true,"description":"Katakana reading as published by the NTA."},"kind":{"type":"string","description":"Corporation kind, in Japanese (株式会社, 有限会社, 合同会社, 国の機関, 地方公共団体, 外国会社等, ...)."},"address":{"$ref":"#/components/schemas/CorporateAddress"},"en_name":{"type":"string","nullable":true,"description":"English name: as registered with the NTA (about 15,000 companies), or from the FSA's EDINET code list for filers such as listed companies (about 4,300). null otherwise."},"closed":{"type":"boolean","description":"true when the registration is closed (merged, dissolved, ...)."},"address_outside":{"type":"string","nullable":true,"description":"Address outside Japan, for foreign companies."},"en_address":{"type":"object","properties":{"prefecture":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"outside":{"type":"string","nullable":true}}},"assignment_date":{"type":"string","nullable":true,"description":"When the corporate number was assigned."},"update_date":{"type":"string","nullable":true},"change_date":{"type":"string","nullable":true},"change_cause":{"type":"string","nullable":true},"close_date":{"type":"string","nullable":true},"close_cause":{"type":"string","nullable":true},"successor_corporate_number":{"type":"string","nullable":true,"description":"Set when the company was absorbed by another."},"search_excluded":{"type":"boolean","description":"true when the NTA excludes the company from name search because its registered head-office address no longer exists (abolished by address renumbering or land readjustment). The company itself still exists; search and resolve do not return it."},"history":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","nullable":true},"address":{"type":"object","properties":{"prefecture":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"street":{"type":"string","nullable":true}}},"change_date":{"type":"string"},"change_cause":{"type":"string","nullable":true}}}}},"required":["corporate_number","name","kind","address","closed","search_excluded","history"]},"AddressComponents":{"type":"object","properties":{"prefecture":{"type":"string","nullable":true},"city":{"type":"string","nullable":true,"description":"Includes the ward for designated cities, e.g. 横浜市中区."},"town":{"type":"string","nullable":true},"chome":{"type":"string","nullable":true},"banchi":{"type":"string","nullable":true},"go":{"type":"string","nullable":true},"building":{"type":"string","nullable":true},"room":{"type":"string","nullable":true},"street_note":{"type":"string","nullable":true,"description":"Kyoto-style street name (通り名) when one was recognised."}}},"AddressIssues":{"type":"array","items":{"type":"string","enum":["prefecture_inferred","ambiguous_city","unknown_prefecture","unknown_town","kyoto_street_name"]}},"PostalEntry":{"type":"object","properties":{"postal_code":{"type":"string","description":"7 digits, no hyphen. Present on every entry, so a search result row carries its own code."},"prefecture":{"type":"string"},"city":{"type":"string"},"town":{"type":"string","nullable":true,"description":"Parenthetical notes from Japan Post are stripped and returned in town_note."},"town_note":{"type":"string","nullable":true,"description":"e.g. 次のビルを除く. Only on kind=general; office entries omit it. The note is stripped from roman.town too and is not repeated there."},"kana":{"type":"object","properties":{"prefecture":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"town":{"type":"string","nullable":true}},"description":"Only on kind=general; office entries omit it (they carry office_kana instead)."},"roman":{"type":"object","properties":{"prefecture":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"town":{"type":"string","nullable":true},"generated":{"type":"boolean","description":"true when the town romanisation was generated from the kana because Japan Post has no row for it."}},"nullable":true,"description":"null when Japan Post has no roman row for the prefecture. Only on kind=general; office entries omit it."},"street":{"type":"string","nullable":true,"description":"Only on kind=office."},"office_name":{"type":"string","nullable":true,"description":"Only on kind=office."},"office_kana":{"type":"string","nullable":true,"description":"Only on kind=office."},"jis_code":{"type":"string","description":"5-digit municipality code (JIS X 0402)."},"kind":{"type":"string","enum":["general","office"]}},"required":["postal_code","prefecture","city","jis_code","kind"]},"Reading":{"type":"object","properties":{"hiragana":{"type":"string"},"confidence":{"type":"number"}},"required":["hiragana","confidence"]},"BusinessOptions":{"type":"object","properties":{"weekend":{"type":"boolean","default":true,"description":"Treat Saturday and Sunday as non-business days."},"year_end":{"type":"boolean","default":true,"description":"Treat 12-29..01-03 as non-business days."},"extra_holidays":{"type":"array","items":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Company holiday."},"maxItems":100},"extra_workdays":{"type":"array","items":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Worked despite being a holiday/weekend; wins over every other rule."},"maxItems":100}},"additionalProperties":false},"SkippedDays":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"reason":{"type":"string","enum":["holiday","year_end","weekend","extra_holiday"]}},"required":["date","reason"]}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_input","unauthorized","plan_required","blocked","free_tier_busy","free_tier_shared_limit","payload_too_large","dataset_unavailable","not_found","internal"]},"message":{"type":"string","description":"Human readable, English."},"field":{"type":"string","description":"Present on invalid_input when a single field is at fault."},"hint":{"type":"string","description":"Present on 429."}},"required":["code","message"]},"PlanLimits":{"type":"object","properties":{"search_max_results":{"type":"integer"},"search_default":{"type":"integer"},"resolve_max_candidates":{"type":"integer"},"history":{"type":"boolean"},"batch":{"type":"boolean"},"batch_max_items":{"type":"integer"}}},"CorporateAddress":{"type":"object","properties":{"prefecture":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true,"description":"7 digits, no hyphen."}}}}}}