Country Data
Beta Documentation
This documentation is currently in beta while the APIs are still be tested.
Country data includes states, cities, counties, and zip codes. Developers can use our APIs to get the data for a given country and provide features such as auto-complete or auto-suggest for city and state names, within their apps. Additionally, our APIs offer geo-coordinates for the center of cities or Pincodes, serving as origin points for distance and range calculations. Each city, state, and country combination is uniquely identified by a cityCode, facilitating name-agnostic analytics and reporting.
Auto-Complete search
The Search API matches input text (both complete or partial name search) against a pre-populated database of locations and returns relevant results (20-50 matches). The API returns 20 results by default and developers can choose to increase or decrease the number of results returned.
Geo-Coding
The Country data includes the latitude and longitude coordinates for a given city or Pincode. The Get City or Pincode APIs can be used to query this lat-long data for the center of a city or pincode.
Unique IDs
When we create the country data within the tenants, each city record within a given state, and country is automatically assigned a unique ID. These IDs are persistent, and can be looked up by location name using APIs. It's important to note that these IDs are unique at the tenant level, which makes it easier for developers to retrieve and update location records such as cities, states, and zip codes.
Country Data Management
During onboarding, every tenant is automatically populated with country-level data, eliminating the need for developers to manually upload this information.
The following guide walks through the use cases for interacting with our Country APIs to retrieve, update, and search for city and state data.
The Search enpoints enables auto-complete search for your application's locations like cities, zip codes, and counties. Under the hood, we pre-populate a tenant's country data, which powers fast and accurate auto-complete results without needing to call external APIs. Furthermore, when the user enters the complete zip code, the API automatically populates the corresponding city, county, and zip code information.
Determine the Location Type
Use the SearchCities, SearchZipCodes, and SearchCounties endpoint to auto-complete and retrieve city, county, or zip code details.
Here, the type can be either - counties, cities, or zipCodes, depending on the location data you’re looking for.
Use Query Parameters for Filtering
Next, you must pass the query prefix parameter to filter your search with a minimum of 2 characters.
The following request would returns all the cities in the Unites States that begin with the prefix sanf
Limiting and Sorting Results
By default, the API returns 20 results. To change this, use the limit query parameter (up to 50). These results are sorted based on relevance.
Users often need to enter location information like addresses, cities, or zip codes. The GetCities endpoint includes the latitude and longitude for that city’s center in the geoCodeCity.This is useful for mapping, logistics, and location-based features.
Path Parameters
Parameter | Data Type | Description | Example |
countryCode | string | The country code for the country. | US |
stateCode | string | The state code for the state. | CA |
cityCode | string | The city code for the city. the format is all one word, all lowercase. | sanfrancisco |
The following example retrieves the details and the city center for San Francisco.
You can retrieve and update your location records, such as cities, states, and zip codes.
Retrieve States
Call GetState to retrieve the details of a specific state. The API retrieves complete details like name, cities, districts, and more. You can also call GetStates to retrieve all states.
The following example retrieves the details for the state of California:
Update State Data
Use the following PUT /countries/{countryCode}/states/{stateCode} endpoint to pass the updated info in the request body to modify state-level information:
Update City Data
You can use the following PUT /countries/{countryCode}/states/{stateCode}/cities/{name} to update city names, counties, aliases, or geocodes about a specific city.
Update Zip Code Data
Use the PUT /countries/{countryCode}/states/{stateCode}/cities/{name}/zipcode endpoint to update information related to a city’s zip code or geoCodeZip: