{"openapi":"3.1.0","info":{"title":"GenAddr Address Generator API","version":"1.0.0","description":"Generate synthetic, format-valid address and profile test data for QA, form validation, demos, and database seed data."},"servers":[{"url":"https://genaddr.com"}],"paths":{"/api/v1/address":{"get":{"summary":"Generate synthetic address test data","operationId":"generateAddress","tags":["Address generator"],"parameters":[{"name":"country","in":"query","schema":{"type":"string","default":"US","example":"US"},"description":"ISO-3166 alpha-2 country code."},{"name":"admin1","in":"query","schema":{"type":"string","example":"CA"},"description":"State, province, prefecture, or region code. Aliases: state, region, province."},{"name":"city","in":"query","schema":{"type":"string","example":"Los-Angeles"},"description":"City or region name. Hyphenated URL values are accepted."},{"name":"postal","in":"query","schema":{"type":"string","example":"650000"},"description":"Postal or ZIP code filter. Aliases: zip, postal_code, postalCode."},{"name":"count","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":1},"description":"Number of records to generate."},{"name":"has_number","in":"query","schema":{"type":"boolean","default":false},"description":"Request numbered street addresses where available. Alias: hasNumber."}],"responses":{"200":{"description":"Synthetic address data generated successfully.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer","example":600}},"X-RateLimit-Remaining":{"schema":{"type":"integer","example":599}},"X-RateLimit-Reset":{"schema":{"type":"integer","example":1760000000}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressResponse"}}}},"400":{"description":"Unsupported country or invalid parameter."},"404":{"description":"No matching state, region, or city was found."},"429":{"description":"Hourly IP rate limit exceeded."}}}}},"components":{"schemas":{"AddressResponse":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"meta":{"type":"object","properties":{"apiVersion":{"type":"string","example":"v1"},"count":{"type":"integer","example":1},"country":{"type":"string","example":"US"},"admin1":{"type":["string","null"],"example":"CA"},"city":{"type":["string","null"],"example":"Los Angeles"},"hasNumber":{"type":"boolean","example":true},"datasetVersion":{"type":"string","example":"2026-06-02"}}},"address":{"$ref":"#/components/schemas/AddressRecord"},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/AddressRecord"}}}},"AddressRecord":{"type":"object","properties":{"country":{"type":"string","example":"US"},"countryName":{"type":"string","example":"United States"},"firstName":{"type":"string","example":"Quinn"},"lastName":{"type":"string","example":"Hayes"},"fullName":{"type":"string","example":"Quinn Hayes"},"street":{"type":"string","example":"9942 Willow Creek Road"},"city":{"type":"string","example":"Los Angeles"},"admin1Code":{"type":"string","example":"CA"},"admin1Name":{"type":"string","example":"California"},"postal":{"type":"string","example":"90001"},"phone":{"type":"string","example":"+1 562 907 2402"},"email":{"type":"string","example":"quinn.hayes@example.com"},"company":{"type":"string","example":"Northstar QA Labs"},"username":{"type":"string","example":"quinnhayes"},"mapsUrl":{"type":["string","null"]},"addressPointVerified":{"type":"boolean","example":true},"mapVerificationLevel":{"type":"string","enum":["address_point","street","city","unverifiable"],"example":"address_point"},"unverifiable":{"type":"object"}}}}}}