Getting started
Welcome to the GeoPostcodes' download API documentation.
The download API enables GeoPostcodes’s customers to explore the list of files they have access to and download the ones they want.
The API is available on https://download.geopostcodes.com together with technical documentation.
In this document, concrete query examples are given to help users start using the Download API.
If you have any questions don't hesitate to contact us at support@geopostcodes.com
Lexicon
SKU stands for Stock Keeping Unit. It refers to any asset which is available for download in this case.
Getting a token
Every API call must be authenticated. The first step is to request a token. This can be done by sending a POST request to https://download.geopostcodes.com/v1/token route with your username and password in the body of the request. The request will then return a token that you must use in the request headers in a field Authorization: Bearer <token> to access the API contents.
The authentication is done using the same credentials as the one used on the customer portal.
Example call:
curl -X POST -d "username=me@my_company.com" -d "password=my_password" https://download.geopostcodes.com/v1/token
Answer:
eyJraWQiOiJQTGdkandMbDFqdWQrUmlmb1hldmlVS1A3bDkyejVwSUM34U9RYytDM21FPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI5YzMwMzVlNy0zOGI5LTQ5ZDQtYmNhZC03ODAxMGVkMWE0MWYiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiY3VzdG9tOmNyZWF0aW9uUGFzc3dvcmQiOiJGZmFBLERRejN8IiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tXC91cy1lYXN0LTFfak9NN1VwYlBKIiwiY29nbml0bzp1c2VybmFtZSI6IjljMzAwNWU3LTM4YjktsDlkNC1iY2FkLTc4MDEwZWQxYTQxZiIsImF1ZCI6IjdxNmI5bTA0aWVobmxqbGFoc3AzcGkxb2NyIiwiZXZlbnRfaWQiOiI0ZjkyNzUwMi1kM2E5LTQxMTMtOWUyNS00ZTUyYmNmYTM0OWQiLCJ0b2tlbl91c2UiOiJpZCIsImF1dGhfdGltZSI6MTY2NDc5MTcxOSwiZXhwIjoxNjY0Nzk1MzE5LCJpYXQiOjE2NjQ3OTE3MTksImVtYWlsIjoiamVyb21lLm1lc3RlcnNAZ2VvcG9zdGNvZGVzLmNvbSJ9.Gc336I57Zmc8q3nxrxaz7n9TXrg88xHnnS_vbTqBs7X4u0pOvr0tOCvcTGrkbS9veHnGtKM1HVvCnzLoWFpk204QoikNZznkF5UDBOPF3HiZzBNnqRRSELvhrd9YX6ORup5TEtbYU3ebgHlCqU6_DYVOl3nuSQ9RmoAY19IFogwSQokSL0Oz1FovCM9CiWSr3ueS3LSUWpWNE_0_TUHNsHq2SfOdA68KD4irL1LdTaYhkMPXAWCZ15wL0zz28uqkp6OzrAbHeiJECC5UlQwbnWytoHcvhYl1BbdqJQynzltrNnr21afX6gaGxKdXYbYarc7LouVUW_oSqYuF44xPMVlQ
Browsing the list of available tags
To get the available list of tags, which can later be used to filter SKUs, send a GET request to https://download.geopostcodes.com/v1/tags
Do not forget to place your token in the request headers in a field Authorization: Bearer <token>.
The query returns you a list of keys available for tags, and the values they can take.
curl --header "Authorization: Bearer <token>" https://download.geopostcodes.com/v1/tags
Here is an example of returned tags, highlighting the "product" and "variant" keys (depending on your subscription, the available values for those tags may differ):
[
{
"key": "product",
"values": [
"postal database"
]
},
{
"key": "variant",
"values": [
"denormalized with geolocation"
]
}
]
Querying available SKUs
A full list of available SKUs can be obtain by sending a GET request to https://download.geopostcodes.com/v1/skus (still with the authorization token in the request headers).
To filter on some specific SKUs tags can be used as well as the "since" parameter which enables to obtain only the SKUs which have been modified after the specified date.
For instance, the following query lists the available SKUs for the postal database product in ASC format for the CD country, which have been updated after Sep14,2022 at2.51PM
curl --header "Authorization: Bearer <token>" "https://download.geopostcodes.com/v1/skus/?tags=format=ASC,country=CD&since=2022-09-08T14:41:12.450Z"
Result:
[
{
"sku":"POST-GEO-CD_ASC",
"tags":{
"format":"ASC",
"variant":"denormalized with geolocation",
"country":"CD",
"product":"postal database"
},
"files":[
{
"name":"GPC-POST-GEO-CD_ASC.zip",
"lastUpdate":"2022-09-19T14:00:04.000Z",
"size":613291
}
]
},
{
"sku":"POST-NOGEO-CD_ASC",
"tags":{
"format":"ASC",
"variant":"denormalized without geolocation",
"country":"CD",
"product":"postal database"
},
"files":[
{
"name":"GPC-POST-NOGEO-CD_ASC.zip",
"lastUpdate":"2022-09-19T14:01:54.000Z",
"size":345019
}
]
}
]
A single SKU can also be queried if you know its name by sending a GET request on https://download.geopostcodes.com/v1/skus/{sku}
For instance:
curl --header "Authorization: Bearer <token>" "https://download.geopostcodes.com/v1/skus/POST-GEO-CD_CSV"
Result:
{
"sku":"POST-GEO-CD_CSV",
"tags":{
"format":"CSV",
"variant":"denormalized with geolocation",
"country":"CD",
"product":"postal database"
},
"files":[
{
"name":"GPC-POST-GEO-CD_CSV.zip",
"lastUpdate":"2022-09-19T14:00:04.000Z",
"size":613694
}
]
}
All these requests on SKUs enable you to obtain the name of the downloadable files (+ their last update time and size in bytes).
Downloading a file
Once you know the name of the file(s) you would like to download, you can send a GET request to https://download.geopostcodes.com/v1/files/{filename} to obtain a pre-signed HTTP download link to actually download the file. Note that the link expires after some time.
For instance, to download the postal database in CSV format for the USA the following request returns the download link:
curl --header "Authorization: Bearer <token>" "https://download.geopostcodes.com/v1/files/GPC-POST-GEO-US_CSV.zip"
Result:
https://d3bk2pb5ctveff.cloudfront.net/GPC-POST-GEO-US_CSV.zip?Expires=1664796454&Key-Pair-Id=K1EFGV0XJJBMCQ&Signature=m5uVQMX4aT4ACj~qNJvqPdQxkYt6gSoCCNt5VHrol9eu2gg79By2HMf1wLrdKSA7~-vLQyO7a1vlm6Fu~XZywHPYzhAv6aXBwXNrresHeV7K1Xvy~~FyagFJTiQehgGMlam-DXUp0JlQqJWhGopYanwMJISZC~IpbVFcdqQpGESaRofbYDkJH76hIj5DVFOtIy03JTUubtrLnnbvepylN4cRIpzllvakOwZFdObbwiTq37FsUlQP-V3LIZ6fqV9DLrBfRtwo-Fz2T84ovHYqnVwbf~ZclsjNXRBIDspN2JZ2lGoK98ePMWHSOIEhV2yknQp~tQfmAnHXjVHTTBVxH6g__