Country Data

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 get /core/api/v1/locations/countries/us/search/cities?query=sa{ "data" { "meta" { "totalcount" 2 }, "data" \[ { "city" "sanfrancisco", "citycode" "sanfrancisco", "county" "sanfrancisco", "state" "california" }, { "city" "sanford", "citycode" "sanford", "county" null, "state" "michigan" } ] }, "request" { "uri" "/core/api/v1/locations/countries/us/search/cities?query=sanf", "method" "get", "querystring" "{\\"query\\" \\"sanf\\"}", "body" {} } } 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 get /core/api/v1/locations/countries/us/states/ca/cities/sanfrancisco{ "data" { "meta" { "totalcount" 26 }, "cities" \[ { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94122", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673777376, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94123", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673777392, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94111", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673777455, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94127", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673777477, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94129", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673777494, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94131", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673777547, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94132", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673777561, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94133", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673777578, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94134", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673777595, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94110", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673777649, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94102", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673777667, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94124", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673776590, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94103", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673776634, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94104", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673776649, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94107", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673776666, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94109", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673776682, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94141", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673776735, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94105", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673776752, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94112", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673776836, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94114", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673777136, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94115", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673777174, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94116", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673777194, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94117", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673777247, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94118", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673777263, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94188", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673777280, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null }, { "tenantid" "os1devs", "countryname" "united states of america", "city" "sanfrancisco", "cityid" "887efce2 8004 42ac 9262 249f4e71f35e", "citycode" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "geocodezip" null, "state" "california", "zipcode" "94121", "county" "sanfrancisco", "alias" \[ "sf", "frisco" ], "createdat" 1694673777295, "createdby" { "id" "1", "name" "abc", "appid" null }, "updatedat" 1694717687104, "updatedby" null } ] }, "request" { "uri" "/core/api/v1/locations/countries/us/states/ca/cities/sanfrancisco", "method" "get", "querystring" "{\\"offset\\" 0}", "body" {} } } "geocodecity" { "lat" "19 0760", "long" "72 8777" } 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 { "data" { "code" "ca", "updatedat" 1694426217981, "tenantid" "os1devs", "createdat" 1694426217981, "updatedby" { "name" "onboarding", "id" "onboarding" }, "id" "36922d5a e1be 4979 ba55 dfa00f3ec932", "createdby" { "name" "onboarding", "id" "onboarding" }, "name" "california" }, "request" { "uri" "/core/api/v1/locations/countries/us/states/ca", "method" "get", "querystring" "{}", "body" {} } } 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 { "statecode" "ca", "statename" "california" } 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 { "cityname" "sanfrancisco", "county" "sanfrancisco", "geocodecity" { "lat" " 7", "long" "159 352229" }, "alias" \[ "sf", "frisco" ] } 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 { "oldzipcode" "94112", "newzipcode" "94115", "geocodezip" { "lat" "90", "long" " 126" } }