Digital Platform API - Postal Code service
The Postal Code Service is a read-only service. This service can be used to retrieve postal code IDs, that are registered with Xandr for geography targeting purposes when setting up a or for configuring reports that support that dimension. The main use case for the Postal Code Service is to keep your postal code database up-to-date with Xandr's. To access the changes that were made to the database since the last call that you made to the service, make sure to use the min_last_modified field in your call.
Warning
Due to the large number of GET calls you would need to make to obtain a complete list of postal codes (as a result of pagination), we recommend the following:
- Create a cache and populate it with a
GETcall for all objects on the service. - Then, for subsequent
GETcalls, use themin_last_modifiedfilter to obtain updates (once per hour or once per day, since postal codes are updated infrequently).
You should only omit the min_last_modified filter if you are querying this service for the first time.
REST API
| HTTP Method | Endpoint | Description |
|---|---|---|
GET |
https://api.appnexus.com/postal-code | View all postal codes using pagination. |
GET |
- https://api.appnexus.com/postal-code?min_last_modified=LAST_MODIFIED - https://api.appnexus.com/postal-code?max_last_modified=LAST_MODIFIED |
View all postal codes since last modified. |
GET |
https://api.appnexus.com/postal-code?country_code=COUNTRY_CODE | View postal codes in a specific country. |
GET |
https://api.appnexus.com/postal-code/meta | Find out which fields you can filter and sort by. |
JSON fields
| Field | Type (Length) | Description |
|---|---|---|
id |
int | The ID of the postal code. |
code |
string | The postal code can be an alphanumeric string of up to 14 characters and can contain a space or hyphen. |
country_id |
string | The ID of the country. |
country_code |
string | The ISO Alpha-2 code for the country to which the city belongs. You can use the Country Service to retrieve a complete list of country codes. |
country_name |
string | The name of the country to which the city belongs. You can use the Country Service to retrieve a complete list of country names. |
last_modified |
timestamp | The date and time when the postal code was last modified. |
active |
Boolean | Designates whether the postal code is active. If true, the postal code is active and available for targeting. If false, there is no geo-location data for the postal code and so targeting is not possible.Note: The postal codes may occasionally become active or inactive based on changes to IP addressing or changes in geolocation technologies, as well as changes to geographical borders. |
Examples
View all postal codes
$ curl -b cookies -c cookies -X GET 'https://api.appnexus.com/postal-code'
{
"response": {
"status": "OK",
"count": 238899,
"start_element": 0,
"num_elements": 100,
"postal_codes": [
{
"id": 120560,
"code": "AD100",
"country_id": "4",
"country_code": "AD",
"country_name": "Andorra"
},
{
"id": 120561,
"code": "AD200",
"country_id": "4",
"country_code": "AD",
"country_name": "Andorra"
},
{
"id": 120562,
"code": "AD300",
"country_id": "4",
"country_code": "AD",
"country_name": "Andorra"
},
{
"id": 120563,
"code": "AD400",
"country_id": "4",
"country_code": "AD",
"country_name": "Andorra"
},
{
"id": 120564,
"code": "AD500",
"country_id": "4",
"country_code": "AD",
"country_name": "Andorra"
},
{
"id": 120565,
"code": "AD600",
"country_id": "4",
"country_code": "AD",
"country_name": "Andorra"
},
{
"id": 120566,
"code": "AD700",
"country_id": "4",
"country_code": "AD",
"country_name": "Andorra"
},
{
"id": 173241,
"code": "1701",
"country_id": "6",
"country_code": "AF",
"country_name": "Afghanistan"
},
{
"id": 173242,
"code": "3001",
"country_id": "6",
"country_code": "AF",
"country_name": "Afghanistan"
},
...
]
}
}
View all postal codes since last modified
$ curl -b cookies -c cookies -X GET 'https://api.appnexus.com/postal-code?min_last_modified=2016-05-18+15:29:37'
{
"response": {
"status": "OK",
"count": 247890,
"start_element": 0,
"num_elements": 100,
"postal_codes": [
{
"id": 1,
"code": "00010",
"active": true,
"country_id": "113",
"country_code": "IT",
"country_name": "Italy",
"last_modified": "2015-09-15 14:40:30"
},
{
"id": 2,
"code": "00011",
"active": true,
"country_id": "113",
"country_code": "IT",
"country_name": "Italy",
"last_modified": "2015-09-15 14:40:32"
},
{
"id": 3,
"code": "00012",
"active": true,
"country_id": "113",
"country_code": "IT",
"country_name": "Italy",
"last_modified": "2015-09-15 17:29:04"
},
{
"id": 4,
"code": "00013",
"active": true,
"country_id": "113",
"country_code": "IT",
"country_name": "Italy",
"last_modified": "2015-09-15 17:29:04"
},
{
"id": 5,
"code": "00015",
"active": true,
"country_id": "113",
"country_code": "IT",
"country_name": "Italy",
"last_modified": "2015-09-15 17:29:05"
},
{
"id": 6,
"code": "00017",
"active": true,
"country_id": "113",
"country_code": "IT",
"country_name": "Italy",
"last_modified": "2015-09-15 17:29:05"
},
{
"id": 7,
"code": "00018",
"active": true,
"country_id": "113",
"country_code": "IT",
"country_name": "Italy",
"last_modified": "2015-09-15 17:29:05"
},
...
]
}
}
View all postal codes in Canada
$ curl -b cookies -c cookies -X GET 'https://api.appnexus.com/postal-code?country_code=CA'
{
"response": {
"status": "OK",
"count": 44101,
"start_element": 0,
"num_elements": 100,
"postal_codes": [
{
"id": 119892,
"code": "A09 0A1",
"country_id": "41",
"country_code": "CA",
"country_name": "Canada"
},
{
"id": 119893,
"code": "A0A 0B3",
"country_id": "41",
"country_code": "CA",
"country_name": "Canada"
},
{
"id": 119894,
"code": "A0A 0C3",
"country_id": "41",
"country_code": "CA",
"country_name": "Canada"
},
{
"id": 119895,
"code": "A0A 1B0",
"country_id": "41",
"country_code": "CA",
"country_name": "Canada"
},
{
"id": 119896,
"code": "A0A 1C0",
"country_id": "41",
"country_code": "CA",
"country_name": "Canada"
},
{
"id": 119897,
"code": "A0A 1E0",
"country_id": "41",
"country_code": "CA",
"country_name": "Canada"
},
...
],
}
}
View postal code by postal code ID
$ curl -b cookies -c cookies 'https://api.appnexus.com/postal-code?id=10'
{
"response": {
"status": "OK",
"count": 1,
"start_element": 0,
"num_elements": 100,
"postal_code": {
"id": 10,
"code": "00021",
"country_id": "113",
"country_code": "IT",
"country_name": "Italy",
"last_modified": "2015-09-15 17:29:05"
}
}
}