{ "openapi": "3.1.0", "info": { "title": "AddressMock Address API", "version": "1.0.0", "summary": "Free, keyless JSON API returning format-correct sample postal addresses.", "description": "Returns sample postal addresses for the United States, Hong Kong, Turkiye and Cabo Verde. No API key, no account, no per-caller quota, and CORS is open, so this endpoint can be called directly from a browser or by an autonomous agent with nothing to provision first.\n\nCity, state, ZIP code and phone area code are always drawn from the same region, so the samples pass region-consistency validation that rejects independently randomised field combinations.\n\nIMPORTANT: responses are format-correct SAMPLE data, not verified deliverable addresses. Street numbers are not guaranteed to exist or to receive mail. The data must not be used for real mail, fraud, impersonation, or bypassing a platform's region or identity checks.", "contact": { "name": "AddressMock support", "email": "support@addressmock.com", "url": "https://addressmock.com/contact" }, "termsOfService": "https://addressmock.com/terms" }, "servers": [ { "url": "https://addressmock.com", "description": "Production" } ], "externalDocs": { "description": "Human-readable API docs", "url": "https://addressmock.com/api" }, "paths": { "/api/addresses": { "get": { "operationId": "generateAddresses", "summary": "Generate sample addresses", "description": "Returns between 1 and 100 sample addresses. Authentication is not supported and not required. Only GET and OPTIONS are accepted; any other method returns 405.", "security": [], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Which address set to sample from. us_tax_free restricts sampling to the five US states with no state sales tax (AK, DE, MT, NH, OR).", "schema": { "type": "string", "enum": [ "us", "us_tax_free", "hk", "cv", "tr" ], "default": "us" } }, { "name": "count", "in": "query", "required": false, "description": "How many records to return. Must be an integer from 1 to 100; anything outside that range returns 400.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }, { "name": "gender", "in": "query", "required": false, "description": "Controls the generated given name.", "schema": { "type": "string", "enum": [ "random", "male", "female" ], "default": "random" } }, { "name": "state", "in": "query", "required": false, "description": "Two-letter US state code. Only applies to type=us and type=us_tax_free; ignored otherwise. An unknown code returns 400, and with type=us_tax_free a state that is not tax-free returns 400. Case-insensitive.", "schema": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ] } }, { "name": "city", "in": "query", "required": false, "description": "US city name. Only applies to type=us and type=us_tax_free; ignored otherwise. Unknown names fall back to a random city in the selected state.", "schema": { "type": "string" }, "example": "Los Angeles" } ], "responses": { "200": { "description": "Generated records.", "headers": { "Access-Control-Allow-Origin": { "description": "Always *", "schema": { "type": "string" } }, "Cache-Control": { "description": "Always no-store", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressResponse" } } } }, "400": { "description": "Invalid count, gender, type, or state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badCount": { "value": { "error": "count must be an integer between 1 and 100" } }, "badType": { "value": { "error": "type must be one of: us, us_tax_free, hk, cv, tr" } }, "notTaxFree": { "value": { "error": "CA is not a tax-free state" } } } } } }, "405": { "description": "Method other than GET or OPTIONS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "badMethod": { "value": { "error": "Only GET is supported" } } } } } } } }, "options": { "operationId": "preflightAddresses", "summary": "CORS preflight", "security": [], "responses": { "204": { "description": "No content. Allowed methods are GET and OPTIONS." } } } } }, "components": { "schemas": { "AddressRecord": { "type": "object", "required": [ "firstName", "lastName", "fullName", "gender", "email", "phone", "street", "unit", "city", "state", "stateName", "zipCode", "country", "fullAddress" ], "properties": { "firstName": { "type": "string", "example": "Emily" }, "lastName": { "type": "string", "example": "Carter" }, "fullName": { "type": "string", "example": "Emily Carter" }, "gender": { "type": "string", "enum": [ "male", "female" ] }, "email": { "type": "string", "format": "email", "description": "Synthetic address on a sample domain. Not a real mailbox." }, "phone": { "type": "string", "description": "US: (XXX) XXX-XXXX with a real area code for the state. HK: +852 plus 8 digits. TR: +90 plus 10 digits starting with 5. CV: +238 plus 7 digits.", "example": "(213) 555-0142" }, "street": { "type": "string", "example": "1420 Wilshire Blvd" }, "unit": { "type": "string", "description": "Secondary unit (Apt / Suite / Unit for us, Daire for tr). The key is always present: it is an empty string for hk and cv records, so callers never have to branch on type.", "example": "Apt 4B" }, "city": { "type": "string", "description": "US city; Hong Kong district; Turkish ilce (district); Cabo Verde city.", "example": "Los Angeles" }, "state": { "type": "string", "description": "Two-letter USPS code for us / us_tax_free. For other types this carries the region code (Hong Kong HKI/KLN/NT, Turkish province plate code, Cabo Verde island code).", "example": "CA" }, "stateName": { "type": "string", "example": "California" }, "zipCode": { "type": "string", "description": "US: 5 digits drawn from that city's real ZIP list, leading zeros preserved. TR: 5 digits whose first two equal the province plate code. CV: 4 digits. HK: empty, because Hong Kong has no postal code.", "example": "90012" }, "country": { "type": "string", "example": "United States", "description": "Literal value returned by the API: \"United States\" for us and us_tax_free, \"Hong Kong\" for hk, \"Turkey\" for tr, \"Cape Verde\" for cv. Note that Turkiye is the official country name adopted at the UN in 2022; the API returns the older \"Turkey\" spelling for backwards compatibility with existing callers.", "enum": [ "United States", "Hong Kong", "Turkey", "Cape Verde" ] }, "fullAddress": { "type": "string", "description": "The record rendered as a single multi-line address in the local convention for its country.", "example": "Emily Carter\n1420 Wilshire Blvd Apt 4B\nLos Angeles, CA 90012\nUnited States" } } }, "AddressResponse": { "type": "object", "required": [ "count", "type", "results", "notice", "docs" ], "properties": { "count": { "type": "integer", "description": "Number of records in results." }, "type": { "type": "string", "description": "Echo of the resolved type parameter." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AddressRecord" } }, "notice": { "type": "string", "description": "Usage disclaimer returned with every response." }, "docs": { "type": "string", "format": "uri" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } }, "x-pricing": { "tier": "free", "price": 0, "currency": "USD", "apiKeyRequired": false, "accountRequired": false, "recordsPerRequestMax": 100, "rateLimit": "No application-level rate limit or per-caller quota. Requests pass through Cloudflare's standard edge protections.", "details": "https://addressmock.com/pricing.md" } }