OS1 Services
Location Service

Country Data

10min

Overview

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.

How it Works

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.

Country Data Use Cases

The following guide walks through the use cases for interacting with our Country APIs to retrieve, update, and search for city and state data.

Use Case: Auto-Complete Search

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

/
Search Cities
Search Cities




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.



Use Case: Retrieve Geo-Coordinates

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.



/
Retrieve Geo-Coordinates
Retrieve Geo-Coordinates

JSON



Use Case: Review and Update City and State Data

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:



Retrieve State


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 State Request body


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 City Data


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:

Update Zip Code




Updated 18 Dec 2023
Did this page help you?
PREVIOUS
Smartphone Tracking
NEXT
Messaging and Mobile Push Notifications
Docs powered by Archbee