Skip to content

List Administrative Areas

List Administrative Areas API returns identifiers of administrative divisions for which Locations API is queryable.
Available administrative divisions are queryable all the way through their hierarchy, obtaining an administrative level detail from its direct parent.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/locations/areas

Path Parameters

Name                       Description Type Examples
*{billing_plan} Billing plan to be applied to the call. string ondemand
*{account_id} Provided identifier of the account. string

Header Parameters

Name                          Description Type Examples                         
*x-api-key Provided API key {x_api_key} that allows authentication. string
*Authorization Provided token {jwt_bearer} that allows authorization. string Bearer {jwt_bearer}

Query Parameters

Name        Description Type Examples Default
country Filter by country. string belgium
spain
  state Filter by state. string bruxelles
comunidad valenciana
    county Filter by county. string bruxelles
alicante
       city Filter by city. string brussel
marina alta
        suburb Filter by suburb. string anderlecht
teulada
page Requested page number for paginated results. int 1
page_size Requested page size for paginated results in the range [1, 100]. int 25
Example
curl -X GET 'https://api.datappeal.io/v4/account/{account_id}/locations/areas?country=italy&state=toscana&county=firenze' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

Status Description
200 List Areas data has been successfully returned.

Body

Areas

Field Description Type Examples
*results Paginated list of requested administrative areas. array[string]
paging Response pagination. Paging
*field Administrative area level of returned results. country
state
county
city
suburb
Paging
Field Description Type
last A relative URI to the last page. string
first A relative URI to the first page. string
prev A relative URI to the previous page. string
next A relative URI to the next page. string
current A relative URI to the current page. string
pages A set of relative URIs calculated around the current page. Page
elements All indexes shown on the current page. array[int]
total The number of all elements that API can retrieve. int
size The selected page size. int
Page
Field Description Type
number Number of the page. int
uri URI of the page. string
Countries
{
    "results": [
        "australia",
        "azerbaijan",
        "cyprus",
        "france",
        "germany",
        "greece",
        "ireland",
        "israel",
        "italy",
        "malta",
        "morocco",
        "netherlands",
        "portugal",
        "qatar",
        "spain",
        "sweden",
        "switzerland",
        "united kingdom",
        "united states"
    ],
    "paging": {
        "last": "/areas?page=1&page_size=25",
        "first": "/areas?page=1&page_size=25",
        "prev": null,
        "next": null,
        "current": "/areas?page=1&page_size=25",
        "pages": [
            {
                "number": 1,
                "uri": "/areas?page=1&page_size=25"
            }
        ],
        "elements": [
            1,
            2,
            3,
            4,
            5,
            6,
            7,
            8,
            9,
            10,
            11,
            12,
            13,
            14,
            15,
            16,
            17,
            18,
            19
        ],
        "total": 19,
        "size": 25
    },
    "field": "country"
}
States by Country
{
    "results": [
        "abruzzo",
        "basilicata",
        "calabria",
        "campania",
        "emilia-romagna",
        "friuli-venezia giulia",
        "lazio",
        "liguria",
        "lombardia",
        "marche",
        "molise",
        "piemonte",
        "puglia",
        "sardegna",
        "sicilia",
        "toscana",
        "trentino-alto adige",
        "umbria",
        "valle d'aosta",
        "veneto"
    ],
    "paging": {
        "last": "/areas?page=1&page_size=25&country=italy",
        "first": "/areas?page=1&page_size=25&country=italy",
        "prev": null,
        "next": null,
        "current": "/areas?page=1&page_size=25&country=italy",
        "pages": [
            {
                "number": 1,
                "uri": "/areas?page=1&page_size=25&country=italy"
            }
        ],
        "elements": [
            1,
            2,
            3,
            4,
            5,
            6,
            7,
            8,
            9,
            10,
            11,
            12,
            13,
            14,
            15,
            16,
            17,
            18,
            19,
            20
        ],
        "total": 20,
        "size": 25
    },
    "field": "state"
}
Counties by State
{
    "results": [
        "arezzo",
        "firenze",
        "grosseto",
        "livorno",
        "lucca",
        "massa carrara",
        "pisa",
        "pistoia",
        "prato",
        "siena"
    ],
    "paging": {
        "last": "/areas?page=1&page_size=25&country=italy&state=toscana",
        "first": "/areas?page=1&page_size=25&country=italy&state=toscana",
        "prev": null,
        "next": null,
        "current": "/areas?page=1&page_size=25&country=italy&state=toscana",
        "pages": [
            {
                "number": 1,
                "uri": "/areas?page=1&page_size=25&country=italy&state=toscana"
            }
        ],
        "elements": [
            1,
            2,
            3,
            4,
            5,
            6,
            7,
            8,
            9,
            10
        ],
        "total": 10,
        "size": 25
    },
    "field": "county"
}
Cities by County
{
    "results": [
        "bagno a ripoli",
        "barberino di mugello",
        "barberino val d' elsa",
        "borgo san lorenzo",
        "calenzano",
        "campi bisenzio",
        "capraia e limite",
        "castelfiorentino",
        "cerreto guidi",
        "certaldo",
        "dicomano",
        "empoli",
        "fiesole",
        "figline valdarno",
        "firenze",
        "firenzuola",
        "fucecchio",
        "gambassi terme",
        "greve in chianti",
        "impruneta",
        "incisa in val d' arno",
        "lastra a signa",
        "londa",
        "marradi",
        "montaione"
    ],
    "paging": {
        "last": "/areas?page=2&page_size=25&country=italy&county=firenze&state=toscana",
        "first": "/areas?page=1&page_size=25&country=italy&county=firenze&state=toscana",
        "prev": null,
        "next": "/areas?page=2&page_size=25&country=italy&county=firenze&state=toscana",
        "current": "/areas?page=1&page_size=25&country=italy&county=firenze&state=toscana",
        "pages": [
            {
                "number": 1,
                "uri": "/areas?page=1&page_size=25&country=italy&county=firenze&state=toscana"
            },
            {
                "number": 2,
                "uri": "/areas?page=2&page_size=25&country=italy&county=firenze&state=toscana"
            }
        ],
        "elements": [
            1,
            2,
            3,
            4,
            5,
            6,
            7,
            8,
            9,
            10,
            11,
            12,
            13,
            14,
            15,
            16,
            17,
            18,
            19,
            20,
            21,
            22,
            23,
            24,
            25
        ],
        "total": 44,
        "size": 25
    },
    "field": "city"
}