{"openapi":"3.1.0","info":{"title":"Address API","version":"1.1.0","description":"Japan address lookup and normalization API. Provides postal code lookup,\naddress normalization, reverse geocoding, batch processing, address validation,\nhistorical address conversion, and format conversion capabilities.\n\n## Internationalization\nAll endpoints that return address data support a \\'lang\\' query parameter:\n- \\'ja\\' (default): Returns Japanese kanji with kana readings and romaji\n- \\'en\\': Returns romanized address fields (prefecture, city, town replaced with romaji)\n- \\'kana\\': Returns katakana address fields\n\n## Romaji Input\nThe normalize endpoint accepts romaji input (e.g., \"Tokyo Shibuya Jinnan 1-23-15\").\nPrefecture names are automatically detected and converted.\n"},"servers":[{"url":"https://address.sakurahub.net","description":"Production server"}],"paths":{"/api/v1/address/postal/{postal_code}":{"get":{"summary":"Look up Japanese address components by 7-digit postal code.","description":"Lookup address components by Japanese postal code (7 digits, with or without hyphen)","operationId":"getAddressByPostalCode","tags":["Address Lookup"],"parameters":[{"name":"postal_code","in":"path","required":true,"description":"Japanese postal code (e.g., \"100-0001\" or \"1000001\")","schema":{"type":"string","pattern":"^\\d{3}-?\\d{4}$"},"example":"100-0001"},{"$ref":"#/components/parameters/lang"}],"responses":{"200":{"description":"Address found","content":{"application/json":{"example":{"postal_code":"100-0001","prefecture":"Tokyo","city":"Chiyodaku","town":"Chiyoda","reading":{"prefecture_kana":"トウキョウト","city_kana":"チヨダク","town_kana":"チヨダ"},"romanized":{"prefecture":"Tokyo","city":"Chiyodaku","town":"Chiyoda"},"coordinates":{"lat":35.6838,"lng":139.7528},"municipality_code":"13101","last_updated":"2026-01-15T00:00:00Z"}}}},"400":{"$ref":"#/components/responses/InvalidPostalCode"},"404":{"$ref":"#/components/responses/AddressNotFound"}}}},"/api/v1/address/normalize":{"post":{"summary":"Normalize a free-text Japanese address into structured fields.","description":"Parse and normalize free-form Japanese address into structured components.\nSupports Japanese (kanji, kana) and romaji input.\nUses hybrid pattern-matching + AI inference for high accuracy.\n","operationId":"normalizeAddress","tags":["Normalization"],"parameters":[{"$ref":"#/components/parameters/lang"}],"requestBody":{"required":true,"content":{"application/json":{"examples":{"japanese":{"summary":"Japanese input","value":{"input":"東京都渋谷区神南1-23-15"}},"romaji":{"summary":"Romaji input","value":{"input":"Tokyo Shibuya Jinnan 1-23-15"}}}}}},"responses":{"200":{"description":"Normalized address","content":{"application/json":{"example":{"normalized":"東京都渋谷区神南1丁目23-15","components":{"prefecture":"東京都","city":"渋谷区","town":"神南","block":"1","number":"23-15"},"confidence":0.95,"coordinates":{"lat":35.6618,"lng":139.6996}}}}},"400":{"description":"Invalid request body","content":{"application/json":{"example":{"error":"VALIDATION_ERROR","code":"ADDR_003","message":"Invalid request body","details":"input field is required"}}}}}}},"/api/v1/address/batch":{"post":{"summary":"Normalize up to 100 Japanese addresses in one batch request.","description":"Normalize multiple addresses in a single request (max 100)","operationId":"batchNormalize","tags":["Normalization"],"requestBody":{"required":true,"content":{"application/json":{"example":{"addresses":["東京都新宿区西新宿2-8-1","大阪府大阪市北区梅田1-1-1"]}}}},"responses":{"200":{"description":"Batch processing results","content":{"application/json":{"example":{"results":[{"input":"東京都新宿区西新宿2-8-1","success":true,"data":{"normalized":"東京都新宿区西新宿2丁目8-1","confidence":0.98}},{"input":"大阪府大阪市北区梅田1-1-1","success":true,"data":{"normalized":"大阪府大阪市北区梅田1丁目1-1","confidence":0.97}}],"processed":2,"successful":2,"failed":0}}}},"400":{"description":"Invalid batch request","content":{"application/json":{"example":{"error":"VALIDATION_ERROR","code":"ADDR_004","message":"Invalid batch request","details":"Maximum 100 addresses per batch"}}}}}}},"/api/v1/address/reverse":{"get":{"summary":"Reverse-geocode a (lat, lng) pair into a Japanese address.","description":"Get nearest address from latitude/longitude coordinates (Japan only)","operationId":"reverseGeocode","tags":["Address Lookup"],"parameters":[{"name":"lat","in":"query","required":true,"description":"Latitude (must be within Japan bounds 20-50)","schema":{"type":"number","minimum":20,"maximum":50},"example":35.6812},{"name":"lng","in":"query","required":true,"description":"Longitude (must be within Japan bounds 120-150)","schema":{"type":"number","minimum":120,"maximum":150},"example":139.7671},{"$ref":"#/components/parameters/lang"}],"responses":{"200":{"description":"Address found","content":{"application/json":{"example":{"postal_code":"100-0005","prefecture":"東京都","city":"千代田区","town":"丸の内","coordinates":{"lat":35.6812,"lng":139.7671}}}}},"400":{"description":"Invalid coordinates","content":{"application/json":{"example":{"error":"VALIDATION_ERROR","code":"ADDR_005","message":"Valid lat and lng query parameters are required"}}}},"404":{"$ref":"#/components/responses/AddressNotFound"}}}},"/api/v1/address/validate":{"post":{"summary":"Validate that a Japanese address exists step-by-step.","description":"Validate a Japanese address step-by-step (prefecture → city → town → block).\nReturns which level the address is valid up to, and suggestions for corrections.\n","operationId":"validateAddress","tags":["Validation"],"parameters":[{"$ref":"#/components/parameters/lang"}],"requestBody":{"required":true,"content":{"application/json":{"example":{"input":"東京都渋谷区神南999丁目"}}}},"responses":{"200":{"description":"Validation result","content":{"application/json":{"example":{"valid":false,"valid_up_to":"town","components":{"prefecture":{"value":"東京都","valid":true},"city":{"value":"渋谷区","valid":true},"town":{"value":"神南","valid":true},"block":{"value":"999丁目","valid":false}},"suggestions":["東京都渋谷区神南1丁目","東京都渋谷区神南2丁目"]}}}}}}},"/api/v1/address/convert-legacy":{"post":{"summary":"Convert a pre-merger Japanese address to its modern form.","description":"Convert old/historical Japanese address to current address.\nHandles municipality mergers, name changes, and boundary changes.\n","operationId":"convertLegacyAddress","tags":["Conversion"],"requestBody":{"required":true,"content":{"application/json":{"example":{"address":"東京府麹町区丸の内1丁目","reference_date":"1940-01-01"}}}},"responses":{"200":{"description":"Conversion result","content":{"application/json":{"example":{"original":"東京府麹町区丸の内1丁目","current":"東京都千代田区丸の内1丁目","changes":[{"date":"1943-07-01","type":"administrative_division","description":"東京府 → 東京都"},{"date":"1947-03-15","type":"merger","description":"麹町区 → 千代田区"}],"postal_code_changed":false}}}}}}},"/health":{"get":{"summary":"Health check","tags":["System"],"responses":{"200":{"description":"Service health status","content":{"application/json":{"example":{"status":"healthy","service":"address","version":"1.1.0","timestamp":"2026-02-14T10:00:00Z"}}}}},"operationId":"getHealth","security":[]}},"/metrics":{"get":{"summary":"API metrics","description":"Returns API metrics in JSON or Prometheus format","tags":["System"],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","prometheus"],"default":"json"},"description":"Response format (json or csv)","example":"json"}],"responses":{"200":{"description":"Service metrics"}},"operationId":"getMetrics"}},"/api/v1/municipalities":{"get":{"summary":"List all Japanese municipalities (cities, towns, villages, wards).","description":"Returns the catalog of Japanese municipalities with their codes\n(JIS X 0402), names (ja/en/kana), prefecture, and population. Use\nas the source of truth for municipality dropdowns.\n","operationId":"listMunicipalities","tags":["Municipalities"],"security":[],"parameters":[{"$ref":"#/components/parameters/lang"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":200,"maximum":2000}}],"responses":{"200":{"description":"Municipality catalog"}}}},"/api/v1/municipalities/{code}":{"get":{"summary":"Get a single municipality by JIS X 0402 code.","description":"Returns the full record for one municipality by its 5-digit JIS code,\nincluding coordinates, population, and prefecture metadata.\n","operationId":"getMunicipality","tags":["Municipalities"],"security":[],"parameters":[{"name":"code","in":"path","required":true,"description":"JIS X 0402 5-digit municipality code.","example":"13104","schema":{"type":"string","pattern":"^\\d{5}$"}},{"$ref":"#/components/parameters/lang"}],"responses":{"200":{"description":"Municipality record"},"404":{"description":"Code not found"}}}},"/api/v1/municipalities/prefectures/list":{"get":{"summary":"List all 47 Japanese prefectures.","description":"Returns the 47 prefectures with names (ja/en/kana), JIS codes (01-47),\nregional grouping (Hokkaido, Tohoku, Kanto, etc.), and capital city.\n","operationId":"listPrefectures","tags":["Municipalities"],"security":[],"parameters":[{"$ref":"#/components/parameters/lang"}],"responses":{"200":{"description":"Prefecture list"}}}},"/api/v1/municipalities/prefecture/{prefecture}":{"get":{"summary":"List municipalities within one prefecture.","operationId":"listMunicipalitiesByPrefecture","description":"Returns all municipalities (cities/towns/villages/wards) within the\nnamed prefecture.\n","tags":["Municipalities"],"security":[],"parameters":[{"name":"prefecture","in":"path","required":true,"description":"Prefecture name in Japanese (e.g. `東京都`) or ISO code (`JP-13`).","example":"東京都","schema":{"type":"string"}},{"$ref":"#/components/parameters/lang"}],"responses":{"200":{"description":"Municipalities in the prefecture"}}}},"/api/v1/google-compat/geocode/json":{"get":{"summary":"Google-Maps-compatible geocode endpoint (drop-in replacement).","description":"Returns geocode results in Google Geocoding API response format. Use\nas a drop-in replacement for client code already using Google Maps\ngeocoding — same query+response schema, free tier available.\n","operationId":"googleGeocode","tags":["Google Compat"],"security":[],"parameters":[{"name":"address","in":"query","required":true,"description":"Address text (Japanese or romaji).","example":"東京都千代田区千代田1-1","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"Response language (`ja` / `en`).","schema":{"type":"string","enum":["ja","en"],"default":"ja"}}],"responses":{"200":{"description":"Geocode results in Google API format"}}}},"/api/v1/google-compat/reverseGeocode/json":{"get":{"summary":"Google-compatible reverse-geocode (lat,lng → address).","description":"Returns reverse-geocode results in Google Geocoding API response\nformat. Drop-in replacement for clients using Google's reverse\ngeocoding.\n","operationId":"googleReverseGeocode","tags":["Google Compat"],"security":[],"parameters":[{"name":"latlng","in":"query","required":true,"description":"`lat,lng` decimal degrees.","example":"35.6812,139.7671","schema":{"type":"string"}}],"responses":{"200":{"description":"Reverse-geocode results"}}}},"/api/v1/google-compat/details/json":{"get":{"summary":"Google-compatible place-details endpoint.","description":"Returns place-detail data in Google Places API \"Details\" response\nformat. Use as a drop-in replacement for the Google Places Details\nAPI for Japanese addresses.\n","operationId":"googlePlaceDetails","tags":["Google Compat"],"security":[],"parameters":[{"name":"place_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Place detail in Google format"}}}},"/api/v1/normalization":{"post":{"summary":"Submit feedback on a normalize-API result (good / bad / suggested-fix).","description":"Submit a feedback record on a previous `/api/v1/address/normalize`\nresult — was it correct? what should it have been? Used to improve\nthe normalization model. Anonymous submissions accepted.\n","operationId":"submitNormalizationFeedback","tags":["Feedback"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["input","vote"],"properties":{"input":{"type":"string","description":"The original input passed to normalize."},"output":{"type":"string","description":"The result the API returned."},"expected":{"type":"string","description":"What the result should have been (optional)."},"vote":{"type":"string","enum":["correct","incorrect","partial"]}}}}}},"responses":{"200":{"description":"Feedback recorded"}}},"get":{"summary":"List recent normalization-feedback entries (admin-filterable).","description":"Returns recent feedback submissions. Admin tokens see all entries;\nnon-admin sees only their own submissions (matched by API key hash).\n","operationId":"listNormalizationFeedback","tags":["Feedback"],"security":[],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"maximum":500}}],"responses":{"200":{"description":"Feedback entries"}}}},"/suggest":{"get":{"summary":"Type-ahead address suggestions for an in-progress query.","description":"Returns a ranked list of address suggestions for an in-progress user\ninput — useful for autocomplete dropdowns. Optimised for low latency.\n","operationId":"suggestAddress","tags":["Address Lookup"],"security":[],"parameters":[{"name":"q","in":"query","required":true,"description":"Partial address input.","example":"東京都渋谷区","schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10,"maximum":50}},{"$ref":"#/components/parameters/lang"}],"responses":{"200":{"description":"Suggestion list"}}}},"/v1/metadata/enums":{"get":{"summary":"List every enum used by the Address API.","description":"Returns the directory of enums (lang codes, format types, prefecture\ncodes) with localised labels. Use when building UIs that mirror the\nAPI's vocabulary.\n","operationId":"listEnums","tags":["Metadata"],"security":[],"responses":{"200":{"description":"Enum metadata"}}}},"/v1/metadata/enums/{name}":{"get":{"summary":"Get one Address API enum (lang, format_type, prefecture) by name.","operationId":"getEnum","tags":["Metadata"],"security":[],"parameters":[{"name":"name","in":"path","required":true,"example":"format_type","schema":{"type":"string"}}],"responses":{"200":{"description":"Enum values"}}}}},"components":{"parameters":{"lang":{"name":"lang","in":"query","required":false,"description":"Response language: ja (default, kanji), en (romaji), kana (katakana)","schema":{"type":"string","enum":["ja","en","kana"],"default":"ja"}}},"responses":{"InvalidPostalCode":{"description":"Invalid postal code format","content":{"application/json":{"example":{"error":"VALIDATION_ERROR","code":"ADDR_001","message":"Postal code must be 7 digits (e.g., 1000001 or 100-0001)"}}}},"AddressNotFound":{"description":"Address not found","content":{"application/json":{"example":{"error":"NOT_FOUND","code":"ADDR_002","message":"No address found"}}}}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key with 'jaddr_' prefix (e.g., 'Bearer jaddr_xxxxx')"}},"schemas":{"Prefecture":{"type":"string","enum":["北海道","青森県","岩手県","宮城県","秋田県","山形県","福島県","茨城県","栃木県","群馬県","埼玉県","千葉県","東京都","神奈川県","新潟県","富山県","石川県","福井県","山梨県","長野県","岐阜県","静岡県","愛知県","三重県","滋賀県","京都府","大阪府","兵庫県","奈良県","和歌山県","鳥取県","島根県","岡山県","広島県","山口県","徳島県","香川県","愛媛県","高知県","福岡県","佐賀県","長崎県","熊本県","大分県","宮崎県","鹿児島県","沖縄県"],"description":"Japanese prefecture name in kanji (47 prefectures)"},"AccuracyLevel":{"type":"string","enum":["exact","block","town","city","prefecture","approximate"],"description":"Geocoding accuracy level"},"NormalizationStatus":{"type":"string","enum":["success","partial","failed"],"description":"Address normalization result status"},"ErrorCode":{"type":"string","enum":["ADDR_001","ADDR_002","ADDR_003","ADDR_004","ADDR_005","ADDR_006","ADDR_007","ADDR_008","ADDR_009","ADDR_010","ADDR_999"],"description":"Error codes:\n- ADDR_001: Invalid postal code format\n- ADDR_002: Address not found (postal code lookup)\n- ADDR_003: Invalid request body (normalization)\n- ADDR_004: Batch processing error\n- ADDR_005: Invalid coordinates\n- ADDR_006: Normalization failed\n- ADDR_007: Address not found (reverse geocoding)\n- ADDR_008: Address validation failed\n- ADDR_009: Historical conversion failed\n- ADDR_010: Format conversion failed\n- ADDR_999: Internal server error\n"},"Address":{"type":"object","properties":{"postal_code":{"type":"string","description":"Japanese postal code in XXX-XXXX format"},"prefecture":{"type":"string","description":"Prefecture name (kanji by default, romaji with lang=en)"},"city":{"type":"string","description":"City/ward name"},"town":{"type":"string","description":"Town/district name"},"reading":{"type":"object","description":"Katakana readings","properties":{"prefecture_kana":{"type":"string"},"city_kana":{"type":"string"},"town_kana":{"type":"string"}}},"romanized":{"type":"object","description":"Romanized (Hepburn) names","properties":{"prefecture":{"type":"string"},"city":{"type":"string"},"town":{"type":"string"}}},"coordinates":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"}}},"municipality_code":{"type":"string","description":"JIS X 0402 municipality code"},"last_updated":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"},"details":{"type":"string"}}}}},"security":[{"ApiKeyAuth":[]}]}