Address by Zipcode

Look up address information by postal code. Queries the local database first; if not found, falls back to an external geocoding service.

Endpoint: POST /biz/bigdata/data/zipcode/address

Parameters

Parameter	Type	Required	Description
zipCode	String	Yes	Postal/zip code to look up
countryCode	String	No	ISO 3166-1 alpha-2 country code (filters results when provided)

Request

curl -X POST "https://api.alaikis.com/std/biz/bigdata/data/zipcode/address" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d 'bizContent={"zipCode": "90210", "countryCode": "US"}'

Response

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": 1001,
      "country": "United States",
      "countryCode": "US",
      "state": "California",
      "stateCode": "CA",
      "city": "Beverly Hills",
      "suburbs": "Beverly Hills",
      "zipCode": "90210",
      "location": "Beverly Hills",
      "latitude": "34.1030",
      "longitude": "-118.4100",
      "createdTime": "2024-01-15T10:30:00",
      "validAdministrativeType": "city",
      "isValid": true
    }
  ]
}

Data Model

Field	Type	Description
id	Integer	Unique record ID
country	String	Country name
countryCode	String	ISO 3166-1 alpha-2 country code
state	String	State/province name
stateCode	String	State/province code
city	String	City name
suburbs	String	Suburb/district name
zipCode	String	Postal/zip code
location	String	Location description
latitude	String	Latitude in decimal degrees
longitude	String	Longitude in decimal degrees
createdTime	String	Record creation timestamp
validAdministrativeType	String	Administrative type validation
isValid	Boolean	Whether the record is validated

Lookup Behavior

1. Local database first: Queries the internal postal code database
2. External fallback: If no results found locally, queries an external geocoding API
3. Country filtering: When countryCode is provided, results are filtered to match the specified country

Error Codes

Code	Description
400	Invalid JSON format
406	Missing required parameter (zipCode)