{"openapi":"3.1.0","info":{"title":"Real Residential Address Generator API","version":"1.0.0"},"servers":[{"url":"https://address.example"}],"paths":{"/api/v1/health":{"get":{"operationId":"health","summary":"Check whether the API process is available.","security":[],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":"ok"}}}}}}},"/api/v1/ready":{"get":{"operationId":"ready","summary":"Check whether the API and PostgreSQL are ready to serve traffic.","security":[],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":"ready"}}}}}}},"/api/v1/countries":{"get":{"operationId":"countries","summary":"List supported countries, capabilities, address counts, and shortcuts.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"data":[{"code":"US","residentialAvailable":true,"residentialCount":50000,"generationMode":"synchronized-pool"}]}}}},"401":{"description":"Missing, expired, or invalid bearer token."},"429":{"description":"Rate limit exceeded. Retry-After is returned in seconds."}}}},"/api/v1/availability":{"get":{"operationId":"availability","summary":"Return the lightweight residential availability list.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"data":[{"code":"US","residentialAvailable":true}]}}}},"401":{"description":"Missing, expired, or invalid bearer token."},"429":{"description":"Rate limit exceeded. Retry-After is returned in seconds."}}}},"/api/v1/client-context":{"get":{"operationId":"client-context","summary":"Resolve country and location context for the request IP.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ip","in":"query","required":false,"description":"Optional IPv4 or IPv6 address; omitted means the request IP.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"data":{"country":"US","region":"California","city":"Los Angeles","matchLevel":"city"}}}}},"401":{"description":"Missing, expired, or invalid bearer token."},"429":{"description":"Rate limit exceeded. Retry-After is returned in seconds."}}}},"/api/v1/locations/search":{"get":{"operationId":"locations","summary":"Search regions, cities, districts, or postcodes with pagination.","security":[{"bearerAuth":[]}],"parameters":[{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 country code.","schema":{"type":"string","default":"US"}},{"name":"field","in":"query","required":false,"description":"Catalog field to return.","schema":{"type":"string","enum":["region","city","district","postcode"],"default":"city"}},{"name":"q","in":"query","required":false,"description":"Optional case-insensitive search text.","schema":{"type":"string"}},{"name":"region","in":"query","required":false,"description":"Exact parent region value.","schema":{"type":"string"}},{"name":"regionId","in":"query","required":false,"description":"Stable parent region ID.","schema":{"type":"string"}},{"name":"cityId","in":"query","required":false,"description":"Stable parent city ID.","schema":{"type":"string"}},{"name":"residential","in":"query","required":false,"description":"Restrict counts to published residential records.","schema":{"type":"boolean","default":false}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned by the previous page.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size from 20 through 200.","schema":{"type":"integer","default":100,"minimum":20,"maximum":200}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"data":{"cities":[{"id":"example-city","value":"Los Angeles","availableCount":120}],"total":1,"nextCursor":null}}}}},"401":{"description":"Missing, expired, or invalid bearer token."},"429":{"description":"Rate limit exceeded. Retry-After is returned in seconds."}}}},"/api/v1/generate":{"get":{"operationId":"generate","summary":"Randomly generate one published residential address and test profile.","security":[{"bearerAuth":[]}],"parameters":[{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 country code.","schema":{"type":"string","default":"US"}},{"name":"region","in":"query","required":false,"description":"Exact first-level region value.","schema":{"type":"string"}},{"name":"regionId","in":"query","required":false,"description":"Stable region ID from location search.","schema":{"type":"string"}},{"name":"city","in":"query","required":false,"description":"Exact city value.","schema":{"type":"string"}},{"name":"cityId","in":"query","required":false,"description":"Stable city ID from location search.","schema":{"type":"string"}},{"name":"district","in":"query","required":false,"description":"Exact district value where supported.","schema":{"type":"string"}},{"name":"districtId","in":"query","required":false,"description":"Stable district ID from location search.","schema":{"type":"string"}},{"name":"postcode","in":"query","required":false,"description":"Exact postcode value.","schema":{"type":"string"}},{"name":"postcodeId","in":"query","required":false,"description":"Stable postcode ID from location search.","schema":{"type":"string"}},{"name":"mode","in":"query","required":false,"description":"Use ip-region to match the request or supplied IP.","schema":{"type":"string","enum":["ip-region"]}},{"name":"ip","in":"query","required":false,"description":"IPv4 or IPv6 used with ip-region mode.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Text that must occur in the selected address components.","schema":{"type":"string"}},{"name":"strategy","in":"query","required":false,"description":"Selection strategy; both modes select from the synchronized database.","schema":{"type":"string","enum":["random","instant"],"default":"random"}},{"name":"residential","in":"query","required":false,"description":"Legacy compatibility flag; generation always returns residential records.","schema":{"type":"boolean","default":true}},{"name":"seed","in":"query","required":false,"description":"Optional reproducible random seed.","schema":{"type":"string"}},{"name":"requestId","in":"query","required":false,"description":"Caller-provided request correlation ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"data":{"requestId":"YOUR_REQUEST_ID","country":"US","mode":"residential","sourcesTried":["address-pool-v2"],"result":{"address":{"id":"address-id","countryCode":"US","formattedAddress":"Example address"}}}}}}},"401":{"description":"Missing, expired, or invalid bearer token."},"429":{"description":"Rate limit exceeded. Retry-After is returned in seconds."}}}},"/api/v1/generate/batch":{"post":{"operationId":"generate-batch","summary":"Generate up to 50 residential addresses with structured filters, exclusions, and uniqueness control.","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["count","filters"],"properties":{"count":{"type":"integer","minimum":1,"maximum":50},"filters":{"type":"object","required":["country"],"additionalProperties":false,"properties":{"country":{"type":"string"},"region":{"type":"string"},"regionId":{"type":"string"},"city":{"type":"string"},"cityId":{"type":"string"},"district":{"type":"string"},"districtId":{"type":"string"},"postcode":{"type":"string"},"postcodeId":{"type":"string"},"q":{"type":"string"}}},"options":{"type":"object","additionalProperties":false,"properties":{"unique":{"type":"boolean","default":true},"seed":{"type":"string"},"strategy":{"type":"string","enum":["random","instant"],"default":"random"},"requestId":{"type":"string"}}},"excludeAddressIds":{"type":"array","maxItems":500,"items":{"type":"string"}}}},"example":{"count":3,"filters":{"country":"US","region":"California","city":"Los Angeles"},"options":{"unique":true,"strategy":"random","seed":"example-seed"},"excludeAddressIds":[]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"data":{"requestId":"batch-request-id","requestedCount":3,"returnedCount":3,"unique":true,"results":[{"address":{"id":"address-id","countryCode":"US"}}]}}}}},"401":{"description":"Missing, expired, or invalid bearer token."},"429":{"description":"Rate limit exceeded. Retry-After is returned in seconds."}}}},"/api/v1/locations/hierarchy":{"get":{"operationId":"location-hierarchy","summary":"List the immediate administrative or postcode children of a country, region, or city.","security":[{"bearerAuth":[]}],"parameters":[{"name":"country","in":"query","required":true,"description":"ISO 3166-1 alpha-2 country code.","schema":{"type":"string"}},{"name":"childType","in":"query","required":true,"description":"Child catalog type to return.","schema":{"type":"string","enum":["region","city","district","postcode"]}},{"name":"parentType","in":"query","required":false,"description":"Type of parent identified by parentId.","schema":{"type":"string","enum":["country","region","city"],"default":"country"}},{"name":"parentId","in":"query","required":false,"description":"Stable region or city ID; omit for a country parent.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Optional child-name search text.","schema":{"type":"string"}},{"name":"residential","in":"query","required":false,"description":"Include residential availability and disable uncovered options.","schema":{"type":"boolean","default":true}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned by the previous page.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size from 20 through 200.","schema":{"type":"integer","default":100,"minimum":20,"maximum":200}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"data":{"parent":{"type":"region","id":"1416"},"childType":"city","children":[{"id":"example-city","value":"Los Angeles","availableCount":120}],"total":1,"nextCursor":null}}}}},"401":{"description":"Missing, expired, or invalid bearer token."},"429":{"description":"Rate limit exceeded. Retry-After is returned in seconds."}}}},"/api/v1/coverage":{"get":{"operationId":"coverage","summary":"Report the three synchronization completion rules for enabled countries.","security":[{"bearerAuth":[]}],"parameters":[{"name":"country","in":"query","required":false,"description":"Optional ISO country code filter.","schema":{"type":"string"}},{"name":"includeComplete","in":"query","required":false,"description":"Include countries that already satisfy all three rules.","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"data":{"countries":[{"countryCode":"US","complete":false,"rules":{"total":{"current":42000,"target":50000,"met":false},"administrativeCoverage":{"actual":0.98,"target":1,"met":false},"regionalMinimums":{"actual":0.95,"target":1,"met":false}}}]}}}}},"401":{"description":"Missing, expired, or invalid bearer token."},"429":{"description":"Rate limit exceeded. Retry-After is returned in seconds."}}}},"/api/v1/addresses/{id}":{"get":{"operationId":"address","summary":"Retrieve a currently published synchronized address by its generated ID.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Address ID returned by generate or batch generation.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"data":{"address":{"id":"pool-v2-address-id","countryCode":"US","formattedAddress":"Example address"}}}}}},"401":{"description":"Missing, expired, or invalid bearer token."},"429":{"description":"Rate limit exceeded. Retry-After is returned in seconds."}}}},"/api/v1/address-translation":{"post":{"operationId":"translation","summary":"Translate a synchronized address into a supported display language.","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["addressId","targetLocale"],"properties":{"addressId":{"type":"string"},"targetLocale":{"type":"string","enum":["en","zh-CN","zh-TW","ja","ko","de","fr","es","pt"]}}},"example":{"addressId":"address-id","targetLocale":"zh-CN"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"data":{"components":{"street":"示例街道","houseNumber":"20"},"lines":["示例地址"],"singleLine":"示例地址"}}}}},"401":{"description":"Missing, expired, or invalid bearer token."},"429":{"description":"Rate limit exceeded. Retry-After is returned in seconds."}}}},"/api/v1/data-health":{"get":{"operationId":"data-health","summary":"Report per-country synchronized-pool health and configuration errors.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"data":{"healthy":true,"countries":[{"code":"US","ready":true,"count":50000}],"configurationErrors":[]}}}}},"401":{"description":"Missing, expired, or invalid bearer token."},"429":{"description":"Rate limit exceeded. Retry-After is returned in seconds."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}