{"openapi":"3.1.0","info":{"title":"Japan Business Tools","version":"0.9.0","description":"Japanese national holidays, business days, Japanese era (wareki), postal codes, address normalization and corporate numbers / 日本の祝日・営業日・和暦・郵便番号・住所の正規化・法人番号"},"servers":[{"url":"https://biz.ossalt.jp"}],"paths":{"/v1/holidays":{"get":{"operationId":"list_holidays","summary":"List Japanese national holidays / 日本の祝日の一覧","description":"List all Japanese national holidays and substitute holidays for a year, based on the National Holidays Act and verified against the Cabinet Office CSV. Each holiday has `name` (descriptive) and `official_name` (as written by the Cabinet Office). / その年の国民の祝日・休日（振替休日・国民の休日を含む）の一覧。name は内容がわかる名前、official_name は内閣府の表記。","parameters":[{"name":"year","in":"query","required":true,"description":"Year (1980-2099) / 年","schema":{"type":"integer","minimum":1980,"maximum":2099,"description":"Year (1980-2099) / 年"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"400":{"description":"Invalid parameters / 入力の誤り","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests / 呼び出しが多すぎます","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Data unavailable / データを読めない","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/business-days/check":{"get":{"operationId":"check_business_day","summary":"Check a business day / 営業日かどうかの判定","description":"Check whether a date is a business day in Japan, and if not, why (weekend, holiday name, bank closure, or a custom closed day). `reason` is Japanese text; `reason_code` is one of weekend, holiday, bank_closure, extra_holiday (null on business days). flags: `estimated`/`unverified` when the year's holidays are an estimate. / その日が営業日かどうかと、休みの理由（土日・祝日の名前・銀行の休業日・指定された休日）。reason_code は weekend・holiday・bank_closure・extra_holiday。","parameters":[{"name":"date","in":"query","required":true,"description":"Date (YYYY-MM-DD) / 日付","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date (YYYY-MM-DD) / 日付","maxLength":200}},{"name":"calendar","in":"query","required":false,"description":"\"standard\": weekends and national holidays are closed. \"bank\": also closed Dec 31 - Jan 3 (Japanese bank holidays). / standard：土日・祝日が休み。bank：加えて12月31日〜1月3日が休み（銀行の休業日）","schema":{"type":"string","enum":["standard","bank"],"default":"standard","description":"\"standard\": weekends and national holidays are closed. \"bank\": also closed Dec 31 - Jan 3 (Japanese bank holidays). / standard：土日・祝日が休み。bank：加えて12月31日〜1月3日が休み（銀行の休業日）","maxLength":200}},{"name":"extra_holidays","in":"query","required":false,"description":"Additional company-specific closed days (e.g. summer break). / 会社独自の休み (comma-separated / カンマ区切り)","schema":{"type":"string","example":"2026-08-13,2026-08-14"}},{"name":"extra_business_days","in":"query","required":false,"description":"Days treated as business days even if they are weekends or holidays. / 休日でも営業日とする日 (comma-separated / カンマ区切り)","schema":{"type":"string","example":"2026-08-13,2026-08-14"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"400":{"description":"Invalid parameters / 入力の誤り","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests / 呼び出しが多すぎます","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Data unavailable / データを読めない","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/business-days/add":{"get":{"operationId":"add_business_days","summary":"Add business days / n営業日後・前","description":"Return the date that is N business days after (or before, if N is negative) the given date. The start date itself is not counted; e.g. 1 business day after a Friday is the next Monday unless it is a holiday. / n営業日後（nが負なら前）の日付。起算日は数えない。","parameters":[{"name":"date","in":"query","required":true,"description":"Start date (YYYY-MM-DD) / 起算日","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Start date (YYYY-MM-DD) / 起算日","maxLength":200}},{"name":"days","in":"query","required":true,"description":"Number of business days (negative = before) / 営業日の数（負なら前）","schema":{"type":"integer","minimum":-2000,"maximum":2000,"description":"Number of business days (negative = before) / 営業日の数（負なら前）"}},{"name":"calendar","in":"query","required":false,"description":"\"standard\": weekends and national holidays are closed. \"bank\": also closed Dec 31 - Jan 3 (Japanese bank holidays). / standard：土日・祝日が休み。bank：加えて12月31日〜1月3日が休み（銀行の休業日）","schema":{"type":"string","enum":["standard","bank"],"default":"standard","description":"\"standard\": weekends and national holidays are closed. \"bank\": also closed Dec 31 - Jan 3 (Japanese bank holidays). / standard：土日・祝日が休み。bank：加えて12月31日〜1月3日が休み（銀行の休業日）","maxLength":200}},{"name":"extra_holidays","in":"query","required":false,"description":"Additional company-specific closed days (e.g. summer break). / 会社独自の休み (comma-separated / カンマ区切り)","schema":{"type":"string","example":"2026-08-13,2026-08-14"}},{"name":"extra_business_days","in":"query","required":false,"description":"Days treated as business days even if they are weekends or holidays. / 休日でも営業日とする日 (comma-separated / カンマ区切り)","schema":{"type":"string","example":"2026-08-13,2026-08-14"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"400":{"description":"Invalid parameters / 入力の誤り","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests / 呼び出しが多すぎます","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Data unavailable / データを読めない","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/business-days/count":{"get":{"operationId":"count_business_days","summary":"Count business days / 期間の営業日数","description":"Count business days from start to end, inclusive of both ends. Returns 0 if start is after end. The period can be up to 3,660 days (about 10 years). / start から end までの営業日の数（両端を含む）。start が end より後なら 0。期間は3,660日（約10年）まで。","parameters":[{"name":"start","in":"query","required":true,"description":"Start date (YYYY-MM-DD) / 開始日","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Start date (YYYY-MM-DD) / 開始日","maxLength":200}},{"name":"end","in":"query","required":true,"description":"End date (YYYY-MM-DD) / 終了日","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"End date (YYYY-MM-DD) / 終了日","maxLength":200}},{"name":"calendar","in":"query","required":false,"description":"\"standard\": weekends and national holidays are closed. \"bank\": also closed Dec 31 - Jan 3 (Japanese bank holidays). / standard：土日・祝日が休み。bank：加えて12月31日〜1月3日が休み（銀行の休業日）","schema":{"type":"string","enum":["standard","bank"],"default":"standard","description":"\"standard\": weekends and national holidays are closed. \"bank\": also closed Dec 31 - Jan 3 (Japanese bank holidays). / standard：土日・祝日が休み。bank：加えて12月31日〜1月3日が休み（銀行の休業日）","maxLength":200}},{"name":"extra_holidays","in":"query","required":false,"description":"Additional company-specific closed days (e.g. summer break). / 会社独自の休み (comma-separated / カンマ区切り)","schema":{"type":"string","example":"2026-08-13,2026-08-14"}},{"name":"extra_business_days","in":"query","required":false,"description":"Days treated as business days even if they are weekends or holidays. / 休日でも営業日とする日 (comma-separated / カンマ区切り)","schema":{"type":"string","example":"2026-08-13,2026-08-14"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"400":{"description":"Invalid parameters / 入力の誤り","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests / 呼び出しが多すぎます","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Data unavailable / データを読めない","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/business-days/adjust":{"get":{"operationId":"adjust_to_business_day","summary":"Adjust to a business day / 休みの日の前倒し・後ろ倒し","description":"If the date is a business day, return it as is; otherwise move to the next (\"next\") or previous (\"previous\") business day. Useful for payment due dates that fall on holidays. / 営業日ならその日、休みなら次（next）または前（previous）の営業日。支払日が休みのときなどに使う。","parameters":[{"name":"date","in":"query","required":true,"description":"Date (YYYY-MM-DD) / 日付","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date (YYYY-MM-DD) / 日付","maxLength":200}},{"name":"direction","in":"query","required":false,"description":"next = 後ろ倒し, previous = 前倒し","schema":{"type":"string","enum":["next","previous"],"default":"next","description":"next = 後ろ倒し, previous = 前倒し","maxLength":200}},{"name":"calendar","in":"query","required":false,"description":"\"standard\": weekends and national holidays are closed. \"bank\": also closed Dec 31 - Jan 3 (Japanese bank holidays). / standard：土日・祝日が休み。bank：加えて12月31日〜1月3日が休み（銀行の休業日）","schema":{"type":"string","enum":["standard","bank"],"default":"standard","description":"\"standard\": weekends and national holidays are closed. \"bank\": also closed Dec 31 - Jan 3 (Japanese bank holidays). / standard：土日・祝日が休み。bank：加えて12月31日〜1月3日が休み（銀行の休業日）","maxLength":200}},{"name":"extra_holidays","in":"query","required":false,"description":"Additional company-specific closed days (e.g. summer break). / 会社独自の休み (comma-separated / カンマ区切り)","schema":{"type":"string","example":"2026-08-13,2026-08-14"}},{"name":"extra_business_days","in":"query","required":false,"description":"Days treated as business days even if they are weekends or holidays. / 休日でも営業日とする日 (comma-separated / カンマ区切り)","schema":{"type":"string","example":"2026-08-13,2026-08-14"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"400":{"description":"Invalid parameters / 入力の誤り","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests / 呼び出しが多すぎます","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Data unavailable / データを読めない","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/business-days/last-of-month":{"get":{"operationId":"last_business_day_of_month","summary":"Last business day of a month / 月末の最終営業日","description":"Return the last business day of the given month. / その月の最終営業日。","parameters":[{"name":"year","in":"query","required":true,"description":"Year (1980-2099) / 年","schema":{"type":"integer","minimum":1980,"maximum":2099,"description":"Year (1980-2099) / 年"}},{"name":"month","in":"query","required":true,"description":"Month (1-12) / 月","schema":{"type":"integer","minimum":1,"maximum":12,"description":"Month (1-12) / 月"}},{"name":"calendar","in":"query","required":false,"description":"\"standard\": weekends and national holidays are closed. \"bank\": also closed Dec 31 - Jan 3 (Japanese bank holidays). / standard：土日・祝日が休み。bank：加えて12月31日〜1月3日が休み（銀行の休業日）","schema":{"type":"string","enum":["standard","bank"],"default":"standard","description":"\"standard\": weekends and national holidays are closed. \"bank\": also closed Dec 31 - Jan 3 (Japanese bank holidays). / standard：土日・祝日が休み。bank：加えて12月31日〜1月3日が休み（銀行の休業日）","maxLength":200}},{"name":"extra_holidays","in":"query","required":false,"description":"Additional company-specific closed days (e.g. summer break). / 会社独自の休み (comma-separated / カンマ区切り)","schema":{"type":"string","example":"2026-08-13,2026-08-14"}},{"name":"extra_business_days","in":"query","required":false,"description":"Days treated as business days even if they are weekends or holidays. / 休日でも営業日とする日 (comma-separated / カンマ区切り)","schema":{"type":"string","example":"2026-08-13,2026-08-14"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"400":{"description":"Invalid parameters / 入力の誤り","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests / 呼び出しが多すぎます","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Data unavailable / データを読めない","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/japanese-era/to-era":{"get":{"operationId":"to_japanese_era","summary":"Convert a date to the Japanese era (wareki) / 西暦から和暦","description":"Convert a Gregorian date (YYYY-MM-DD) to the Japanese era calendar, e.g. 2026-10-07 → 令和8年10月7日 (wareki_short R8.10.07, zero-padded). Year 1 is written 元年. Supported from 1873-01-01 (the Gregorian calendar was adopted on 明治6年1月1日). Eras: 令和 (R) from 2019-05-01, 平成 (H) from 1989-01-08, 昭和 (S) from 1926-12-25, 大正 (T) from 1912-07-30, 明治 (M) from 1868-01-25. flags: `assumes_current_era` for dates after today (the era might change). / 西暦の日付を和暦にする。1年目は「元年」。明治6年（1873年）1月1日から。今日より後の日付には assumes_current_era。","parameters":[{"name":"date","in":"query","required":true,"description":"Date (YYYY-MM-DD) / 日付","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date (YYYY-MM-DD) / 日付","maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"400":{"description":"Invalid parameters / 入力の誤り","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests / 呼び出しが多すぎます","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Data unavailable / データを読めない","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/japanese-era/from-era":{"get":{"operationId":"from_japanese_era","summary":"Convert a Japanese era date (wareki) to a Gregorian date / 和暦から西暦","description":"Convert a Japanese era date to YYYY-MM-DD. Accepts 令和8年10月7日, 令和元年5月1日, R8.10.7, H31/4/30, Reiwa 8.10.7, kanji numerals (昭和六十四年一月七日), a trailing weekday such as （水） or 水曜日, and full-width characters. `input_era`/`input_era_year` echo the input; `actual` is the correct era for that date. If the date is outside the input era (e.g. 平成31年5月1日, written after the era changed), it is still converted by counting years, `within_era` is false and flags has `outside_era`. If a weekday was given and does not match, `weekday_matches` is false and flags has `weekday_mismatch`. / 和暦の日付を西暦にする。元号の範囲の外（平成31年5月1日など）も年を数えて変換し、within_era が false・flags に outside_era。曜日が合わなければ weekday_mismatch。","parameters":[{"name":"wareki","in":"query","required":true,"description":"Japanese era date, e.g. 令和8年10月7日 or R8.10.7 / 和暦の日付","schema":{"type":"string","description":"Japanese era date, e.g. 令和8年10月7日 or R8.10.7 / 和暦の日付","maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"400":{"description":"Invalid parameters / 入力の誤り","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests / 呼び出しが多すぎます","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Data unavailable / データを読めない","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/postal-codes/lookup":{"get":{"operationId":"lookup_postal_code","summary":"Look up a Japanese postal code / 郵便番号から住所","description":"Look up the address (prefecture, city, town) for a 7-digit Japanese postal code, from Japan Post data. Accepts forms like 1000001, 100-0001 or 〒100-0001. One code can cover several towns; all are returned. `town_detail` holds the parenthesized part as written by Japan Post (e.g. chome ranges or building floors). If the code is a business-specific code (大口事業所個別番号) or a PO box code, the business is returned in `offices`. / 郵便番号から住所（都道府県・市区町村・町域）。日本郵便のデータ。1つの郵便番号に町域が複数あれば、すべて返す。事業所の個別郵便番号なら、事業所名と所在地を offices に返す。","parameters":[{"name":"postal_code","in":"query","required":true,"description":"7-digit postal code, hyphen optional / 郵便番号（7桁、ハイフンは任意）","schema":{"type":"string","description":"7-digit postal code, hyphen optional / 郵便番号（7桁、ハイフンは任意）","maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"400":{"description":"Invalid parameters / 入力の誤り","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests / 呼び出しが多すぎます","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Data unavailable / データを読めない","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/postal-codes/search":{"get":{"operationId":"search_postal_code","summary":"Find postal codes by address / 住所から郵便番号","description":"Find Japanese postal codes by prefecture, city and (optionally) part of the town name, from Japan Post data. The city must be the full municipality name (e.g. 札幌市中央区, 新宿区); the county name may be omitted. With `office_name`, searches business-specific codes (大口事業所個別番号) of businesses in that city by name instead. Returns up to 100 matches. / 都道府県・市区町村・町域（部分一致、任意）から郵便番号を探す。市区町村は正式な名前で（郡名は省いてよい）。office_name を指定すると、その市区町村の事業所の個別郵便番号を事業所名（部分一致）で探す。","parameters":[{"name":"prefecture","in":"query","required":false,"description":"Prefecture, e.g. 東京都 (optional) / 都道府県（任意）","schema":{"type":"string","description":"Prefecture, e.g. 東京都 (optional) / 都道府県（任意）","maxLength":200}},{"name":"city","in":"query","required":true,"description":"Municipality, e.g. 新宿区 / 市区町村","schema":{"type":"string","description":"Municipality, e.g. 新宿区 / 市区町村","maxLength":200}},{"name":"town","in":"query","required":false,"description":"Part of the town name, e.g. 西新宿 (optional) / 町域の一部（任意）","schema":{"type":"string","description":"Part of the town name, e.g. 西新宿 (optional) / 町域の一部（任意）","maxLength":200}},{"name":"office_name","in":"query","required":false,"description":"Part of a business name, in kanji or katakana (optional) / 事業所名の一部（任意）","schema":{"type":"string","description":"Part of a business name, in kanji or katakana (optional) / 事業所名の一部（任意）","maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"400":{"description":"Invalid parameters / 入力の誤り","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests / 呼び出しが多すぎます","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Data unavailable / データを読めない","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/addresses/normalize":{"get":{"operationId":"normalize_address","summary":"Normalize a Japanese address (to town level) / 住所の正規化（町域まで）","description":"Split a Japanese address into prefecture, city, town and the rest (block numbers, building), matching Japan Post's address data, and return candidate postal codes. Absorbs full/half-width, spacing, kanji vs. arabic numerals, ヶ/ケ and omitted county names; fills in the prefecture when the city is unique. Does NOT verify block/house numbers and has no coordinates. `level` tells how far the match went: 0 = nothing matched, 1 = prefecture only (see `city_candidates` if the city name is ambiguous), 2 = city matched but not the town (`postal_codes` are city-wide candidates), 3 = town matched. `address` and `municipality_code` are null below level 2. flags: `partial` (level below 3), `ambiguous` (several city or postal code candidates — ask the user or show all). / 住所を都道府県・市区町村・町域・残り（番地・建物名など）に分け、郵便番号の候補を返す（日本郵便のデータにあてはめる）。番地が実在するかの確認と緯度・経度はない。level：0＝わからない、1＝都道府県まで、2＝市区町村まで（町域はわからない）、3＝町域まで。","parameters":[{"name":"address","in":"query","required":true,"description":"Japanese address, e.g. 北海道札幌市中央区大通西10丁目1-1 / 住所","schema":{"type":"string","description":"Japanese address, e.g. 北海道札幌市中央区大通西10丁目1-1 / 住所","maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"400":{"description":"Invalid parameters / 入力の誤り","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests / 呼び出しが多すぎます","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Data unavailable / データを読めない","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/corporations/lookup":{"get":{"operationId":"lookup_corporate_number","summary":"Look up a Japanese corporate number / 法人番号から法人の情報","description":"Look up a 13-digit Japanese corporate number (法人番号) in the National Tax Agency's monthly bulk data: name, furigana, English name, kind, registered address and postal code, assignment date, and closure (date, cause, successor) if the registry record was closed. The check digit (first digit) is verified first; a wrong check digit is reported as an input error. flags: `closed` (the registry record is closed — tell the user), `excluded_from_search`, `not_found`. This is not the invoice (qualified invoice issuer) registry. / 法人番号（13桁）から、名前・フリガナ・英語の名前・法人の種類・所在地・郵便番号・指定の日・閉鎖の日と事由・承継先を返す。国税庁の全件データ（月1回）。先頭の1桁（チェックデジット）を確かめ、合わなければ入力の誤りとして返す。インボイス（適格請求書発行事業者）の登録の確認ではない。","parameters":[{"name":"corporate_number","in":"query","required":true,"description":"13-digit corporate number, hyphens/spaces allowed / 法人番号（13桁。ハイフン・空白は任意）","schema":{"type":"string","description":"13-digit corporate number, hyphens/spaces allowed / 法人番号（13桁。ハイフン・空白は任意）","maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"400":{"description":"Invalid parameters / 入力の誤り","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests / 呼び出しが多すぎます","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Data unavailable / データを読めない","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/corporations/search":{"get":{"operationId":"search_corporation_by_name","summary":"Find corporate numbers by name / 法人の名前から法人番号","description":"Find Japanese corporations whose name starts with the given text (prefix match), in the National Tax Agency's monthly bulk data. Legal-form words such as 株式会社 or 一般社団法人 are ignored at either end, and full/half-width and spaces are normalized. Matching in the middle of a name and furigana search are not supported. flags: `truncated`, `exact_match_only` (too many names start with the input; only exact matches returned), `not_found`. Returns up to 100 matches (`total`, `returned`, `truncated`) with corporate number, name, prefecture, city and `is_closed` (registry record closed); use lookup_corporate_number for details. Corporations marked as excluded from search on the NTA site are not included. / 名前の先頭から合う法人を探す（前方一致）。株式会社などの言葉は前後どちらにあっても無視し、全角・半角や空白の違いも吸収する。名前の途中からの検索とフリガナの検索はできない。最大100件。詳しい情報は lookup_corporate_number で。国税庁のサイトで検索対象除外の法人は入っていない。","parameters":[{"name":"name","in":"query","required":true,"description":"Beginning of the corporate name (e.g. トヨタ自動車) / 法人の名前の先頭（例：トヨタ自動車）","schema":{"type":"string","description":"Beginning of the corporate name (e.g. トヨタ自動車) / 法人の名前の先頭（例：トヨタ自動車）","maxLength":200}},{"name":"prefecture","in":"query","required":false,"description":"Prefecture to narrow down (optional, e.g. 東京都 or 東京) / 都道府県で絞り込む（任意）","schema":{"type":"string","description":"Prefecture to narrow down (optional, e.g. 東京都 or 東京) / 都道府県で絞り込む（任意）","maxLength":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"400":{"description":"Invalid parameters / 入力の誤り","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests / 呼び出しが多すぎます","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Data unavailable / データを読めない","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Answer":{"type":"object","required":["result","source","as_of","notes","flags"],"properties":{"result":{"type":"object","description":"The answer / 結果"},"source":{"type":"object","description":"Source and verification / 出典と照合の状況"},"as_of":{"type":"string","description":"Reference date in Japan time (YYYY-MM-DD) / 基準日（日本時間）"},"notes":{"type":"array","items":{"type":"string"},"description":"Assumptions such as estimated values / 前提（見込みの値など）"},"flags":{"type":"array","items":{"type":"string"},"description":"`flags` holds machine-readable codes: `estimated` (a value is an estimate, e.g. a future equinox day — tell the user), `unverified` (year not yet checked against Cabinet Office data — tell the user), `assumes_current_era` (a future date written in the current era — tell the user), `outside_era` (the era date given is outside that era), `weekday_mismatch`, `closed` (the company's registry record is closed — tell the user), `excluded_from_search`, `truncated`, `not_found`, `exact_match_only`, `partial`, `ambiguous`, `city_not_found`, `ambiguous_city`."}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"type":{"type":"string","enum":["invalid_input","server_error"]}}}}}}