Partager via

Digital Platform API - City service

  • Article

The read-only City Service allows you to see information about the cities registered in the Xandr system, including the region, designated market area, and country to which each city belongs. You can use this service to retrieve the IDs of cities for targeting in campaigns (see city_targets in the Profile Service).

REST API

HTTP Method Endpoint Description
GET https://api.appnexus.com/city View all cities.
GET https://api.appnexus.com/city?country_code=COUNTRY_CODE View all cities in a specific country.
GET https://api.appnexus.com/city?country_name=COUNTRY_NAME View all cities in a specific country.
GET https://api.appnexus.com/city?dma_id=DMA_ID View all cities in a specific designated market area.
GET https://api.appnexus.com/city?dma_name=DMA_NAME View all cities in a specific designated market area.
GET https://api.appnexus.com/city?id=ID View a specific city by ID.
GET https://api.appnexus.com/city?name=NAME View a specific city by name.
GET https://api.appnexus.com/city/meta Find out which fields you can filter and sort by.

JSON fields

Field Type Description
id int The ID of the city.
name string The name of the city.
country_id int The ID of the country to which the city belongs. You can use the Country Service to retrieve a complete list of country IDs.
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.
country_code string The ISO code for the country to which the city belongs. You can use the Country Service to retrieve a complete list of country codes.
region_id int The ID of the region to which the city belongs. You can use the Region Service to retrieve a complete list of region IDs.
region_name string The name of the region to which the city belongs. You can use the Region Service to retrieve a complete list of region names.
region_code string The ISO or FIPS code for the region to which the city belongs. You can use the Region Service to retrieve a complete list of region codes.
dma_id int The ID of the designated market area to which the city belongs. You can use the Designated Market Area Service to retrieve a complete list of DMA IDs.
dma_name string The name of the designated market area to which the city belongs. You can use the Designated Market Area Service to retrieve a complete list of DMA names.
active Boolean If true, the city is available for targeting. If false, there is no geolocation data for the city and so delivery is not possible.

Examples

View all cities in Germany

$ curl -b cookies -c cookies 'https://api.appnexus.com/city?country_code=DE'
{
    "response": {
        "status": "OK",
        "count": 15769,
        "start_element": 0,
        "num_elements": 100,
        "cities": [
            {
                "id": 36677,
                "name": "Aach",
                "region_id": 825,
                "region_name": "Baden-Wurttemberg",
                "region_code": "01",
                "country_id": 59,
                "country_name": "Germany",
                "country_code": "DE",
                "dma_id": 1,
                "dma_name": "--",
                "active": true,
                "last_modified": "2015-04-09 19:40:57"
            },
            {
                "id": 36678,
                "name": "Aalen",
                "region_id": 825,
                "region_name": "Baden-Wurttemberg",
                "region_code": "01",
                "country_id": 59,
                "country_name": "Germany",
                "country_code": "DE",
                "dma_id": 1,
                "dma_name": "--",
                "active": true,
                "last_modified": "2015-04-09 19:40:57"
            },
            {
                "id": 36679,
                "name": "Abstatt",
                "region_id": 825,
                "region_name": "Baden-Wurttemberg",
                "region_code": "01",
                "country_id": 59,
                "country_name": "Germany",
                "country_code": "DE",
                "dma_id": 1,
                "dma_name": "--",
                "active": true,
                "last_modified": "2015-04-09 19:40:57"
            },
            ...
        ]
    }
}

View all cities in the Bayern region of Germany

$ curl -b cookies -c cookies 'https://api.appnexus.com/city?region_name=Bayern'
{
  "response": {
    "status": "OK",
    "count": 3066,
    "start_element": 0,
    "num_elements": 100,
    "cities": [
      {
        "id": 39026,
        "name": "Abenberg",
        "region_id": 826,
        "region_name": "Bayern",
        "region_code": "02",
        "country_id": 59,
        "country_name": "Germany",
        "country_code": "DE",
        "dma_id": 1,
        "dma_name": "--",
        "active": true,
        "last_modified": "2015-04-09 19:40:57"
      },
      {
        "id": 39027,
        "name": "Abensberg",
        "region_id": 826,
        "region_name": "Bayern",
        "region_code": "02",
        "country_id": 59,
        "country_name": "Germany",
        "country_code": "DE",
        "dma_id": 1,
        "dma_name": "--",
        "active": true,
        "last_modified": "2015-04-09 19:40:57"
      },
      {
        "id": 39028,
        "name": "Absberg",
        "region_id": 826,
        "region_name": "Bayern",
        "region_code": "02",
        "country_id": 59,
        "country_name": "Germany",
        "country_code": "DE",
        "dma_id": 1,
        "dma_name": "--",
        "active": true,
        "last_modified": "2015-04-09 19:40:57"
      },
      ...
    ]
  }
}

View all cities named "Karlsruhe"

$ curl -b cookies -c cookies 'https://api.appnexus.com/city?name=Karlsruhe'
{
    "response": {
        "status": "OK",
        "count": 2,
        "start_element": 0,
        "num_elements": 100,
        "cities": [
            {
                "id": 37739,
                "name": "Karlsruhe",
                "region_id": 825,
                "region_name": "Baden-Wurttemberg",
                "region_code": "01",
                "country_id": 59,
                "country_name": "Germany",
                "country_code": "DE",
                "dma_id": 1,
                "dma_name": "--",
                "active": true,
                "last_modified": "2015-04-09 19:40:57"
            },
            {
                "id": 195431,
                "name": "Karlsruhe",
                "region_id": 3952,
                "region_name": "North Dakota",
                "region_code": "ND",
                "country_id": 233,
                "country_name": "United States",
                "country_code": "US",
                "dma_id": 687,
                "dma_name": "Minot-Bismarck-Dickinson(Williston) ND",
                "active": false,
                "last_modified": "2016-10-19 05:01:12"
            }
        ]
    }
}