Smart Zipcode Area

Keyword-based smart postal code detection. Search by country code and keyword, matching against both city names (fuzzy) and postal codes (exact).

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

Parameters

Parameter	Type	Required	Description
country_code	String	Yes	ISO 3166-1 alpha-2 country code
keyword	String	Yes	Search keyword (matches city name or postal code)

The keyword parameter performs a fuzzy match on city names (LIKE %keyword%) and an exact match on postal codes. Results are limited to 100 records.

Request

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

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

Use Cases

• Autocomplete: Use as a type-ahead search for postal code input fields
• Address validation: Verify city-postal code combinations
• Location lookup: Find postal codes by city name fragment

Error Codes

Code	Description
400	Invalid JSON format
406	Missing required parameters (country_code and keyword)