Its been a really really busy few months and the blog posts have been slow. This one is more of a documentation to myself, but the new location API may be useful to you, and you may have additional sources of data!

The idea is simple. How many times have you needed an API you can call to get the states (provinces) in a country? How many times have you needed to drill down to counties? Cities? Postal codes?

This API is meant for that purpose.

At present, it’s really not thoroughly tested and is really only complete for the US. South Africa is partially done and hopefully, the UK will be next (data anyone?).

Caveat

Before using this API you should be aware that it is free and unrestricted for now. Depending on usage I may need to allow access through a free API key and if I really struggle I may in the future need to charge for access, at least in some freemium way. I’m hoping to avoid that but in order to not have to charge money, if you do use this API please cache all the data. Cache for at least a week but longer if possible, address info doesn’t change often!

Usage

Usages is a REST like API returning data in JSON.

There are 4 levels of queries:

1. Country
2. Region (province / state)
3. County (optional)
4. City (includes zip codes)

Country

To get country data simply call the country endpoint of the location API:

https://api.softsmart.co.za/location/country/

This will return a list of countries (obviously 🙂 like this:

[{"id":1,"name":"Afghanistan","code":"af","modified":"2019-12-03 11:44:40","created":"2019-12-03 11:44:40"},{"id":3,"name":"Albania","code":"al","modified":"2019-12-03 11:52:28","created":"2019-12-03 11:52:28"},{"id":4,"name":"Algeria","code":"dz","modified":"2019-12-03 11:52:28","created":"2019-12-03 11:52:28"},{"id":5,"name":"Andorra","code":"ad","modified":"2019-12-03 11:54:53","created":"2019-12-03 11:54:53"},{"id":6,"name":"Angola","code":"ao","modified":"2019-12-03 11:54:53","created":"2019-12-03 11:54:53"},{"id":7,"name":"Anguilla","code":"ai","modified":".....

Region

To get a list of regions (provinces/states), call the region endpoint and pass in a country code (2 character country code), like this:

https://api.softsmart.co.za/location/region/?country=us

That will return a list of regions for that country, like this:

[{"id":267,"countryId":218,"name":"Alabama","code":"AL","modified":"2020-01-26 23:38:11","created":"2020-01-26 23:38:11"},{"id":268,"countryId":218,"name":"Alaska","code":"AK","modified":"2020-01-26 23:38:11","created":"2020-01-26 23:38:11"},

The important bits there being name and code, ie, Alabama and AL in the first line above.

County

County is an optional field. Certain countries like the US use them. Call a county by passing in a 2 character region field, like TX for texas:

https://api.softsmart.co.za/location/county/?region=tx

And you guessed it, this returns a list of counties in that region, like this:

[{"id":2460,"name":"Travis County","regionName":"Texas","regionCode":"TX","regionId":"310","countryId":218,"countryCode":"","modified":"2020-01-27 12:24:03","created":"2020-01-27 12:24:03"},{"id":2488,"name":"Sherman County","regionName":"Texas","regionCode":"TX","regionId":"310","countryId":218,"countryCode":"","modified":"2020-01-27 12:24:04","created":"2020-01-27 12:24:04"}

City

Finally we get to city data. Call city data by either passing in a county name or a 2 character region code, or both (in some cases you’ll HAVE to pass in both, see below). Like this:

https://api.softsmart.co.za/location/city/?region=ca
https://api.softsmart.co.za/location/city/?county=Travis%20County
https://api.softsmart.co.za/location/city/?region=tx&county=Dallas%20County

That will return city data like this:

[{"id":22889,"regionId":310,"regionName":"Texas","regionCode":"TX","countryId":218,"countryCode":"us","countyId":2460,"countyName":"Travis County","name":"Austin","zip":"73301","modified":"2020-01-27 15:26:10","created":"2020-01-27 15:26:10"},{"id":24514,"regionId":310,"regionName":"Texas","regionCode":"TX","countryId":218,"countryCode":"us","countyId":2460,"countyName":"Travis County","name":"Del Valle","zip":"78617","modified":"2020-01-27 15:27:13","created":"2020-01-27 15:27:13"},

Errors

In some cases, you may get errors back. They should hopefully be self-explanatory. For instance, if you called the city endpoint with only Dallas County, like this:

https://api.softsmart.co.za/location/city/?county=Dallas%20County

You’ll get back an error like this:

{"error":true,"message":"5 counties exists with name Dallas County. Please use the region parameter to specify which county you're looking for"}

This error is telling you that there are five counties in the US called Dallas County and you have to also pass in the region code to select the correct county.

Use Responsibly

As already mentioned, I’d love to keep this open and free. Please respect that and cache your data. Also if you have data for other countries please get in touch!