Geo API

FreeAPIService documentation. Back to the test console.

← Back to the test console

Examples below use $BASE_URL, the base URL where this API is hosted:

BASE_URL="http://your-host"

Base path: /geo

Read-only lookups over the geo_country and geo_city tables. All responses are JSON.

Two response shapes are used:

Pagination and sorting (paged routes)

Query parameter Default Description
limit 100 Rows per page, capped at 1000. Invalid or <= 0 values fall back to the default.
offset 0 Rows to skip. Negative values fall back to 0.
sort varies Column to sort by. Only whitelisted columns are honored; otherwise the route default is used.
order ASC DESC for descending; anything else is treated as ASC.

Filters are exact matches. Unknown query parameters are ignored.

GET /geo/countries

Lists countries (geo_country).

Query parameters

Parameter Description
name Exact country name.
iso_3166_code Exact ISO 3166 code (e.g. IT).
sort name (default) or iso_3166_code.
order ASC (default) or DESC.
limit, offset Pagination.

Example

curl "$BASE_URL/geo/countries?limit=2"

{
    "count": 2,
    "limit": 2,
    "offset": 0,
    "rows": [
        { "iso_3166_code": "AF", "name": "Afghanistan" },
        { "iso_3166_code": "AL", "name": "Albania" }
    ],
    "total": 249
}

Filter by code:

curl "$BASE_URL/geo/countries?iso_3166_code=IT"

GET /geo/countries/search

Searches countries by a partial name (LIKE %name%).

Query parameters

Parameter Required Description
name yes Substring to search for.
limit, offset no Pagination.

Responses

Status Body
200 Paged result
400 { "error": "name is mandatory" }

Example

curl "$BASE_URL/geo/countries/search?name=ita"

{
    "count": 5,
    "limit": 100,
    "offset": 0,
    "rows": [
        { "iso_3166_code": "SA", "name": "Arabia Saudita" },
        { "iso_3166_code": "VG", "name": "Isole Vergini britanniche" },
        { "iso_3166_code": "IT", "name": "Italia" },
        { "iso_3166_code": "MR", "name": "Mauritania" },
        { "iso_3166_code": "IO", "name": "Territorio britannico dell’Oceano Indiano" }
    ],
    "total": 5
}

GET /geo/countries/:iso

Returns a single country by ISO 3166 code (case-insensitive).

Path parameters

Parameter Required Description
iso yes ISO 3166 code, e.g. IT.

Responses

Status Body
200 The country object
400 { "error": "iso is mandatory" }
404 { "error": "country not found" }

Example

curl "$BASE_URL/geo/countries/ad"

{
    "iso_3166_code": "AD",
    "name": "Andorra"
}

GET /geo/cities

Lists cities (geo_city), with any combination of exact-match filters.

Query parameters

Parameter Description
country_code Country code (e.g. IT).
city Exact city name.
zip ZIP code (kept as text, leading zeros meaningful).
province_code Province code (e.g. PD).
province Exact province name.
region_code Numeric region code.
region Exact region name.
catastral_code Belfiore/catastral code (e.g. A001).
sort Any of the columns above; default city.
order ASC (default) or DESC.
limit, offset Pagination.

Example

curl "$BASE_URL/geo/cities?city=Alessandria&limit=2&sort=zip&order=DESC"

{
    "count": 2,
    "limit": 2,
    "offset": 0,
    "rows": [
        {
            "catastral_code": "A182",
            "city": "Alessandria",
            "country_code": "IT",
            "province": "Alessandria",
            "province_code": "AL",
            "region": "Piemonte",
            "region_code": 1,
            "zip": "15122"
        },
        {
            "catastral_code": "A182",
            "city": "Alessandria",
            "country_code": "IT",
            "province": "Alessandria",
            "province_code": "AL",
            "region": "Piemonte",
            "region_code": 1,
            "zip": "15121"
        }
    ],
    "total": 2
}

GET /geo/cities/search

Searches cities by a partial name, optionally restricted to a country.

Query parameters

Parameter Required Description
city yes Substring to search for.
country_code no Restrict results to this country.
limit, offset no Pagination.

Responses

Status Body
200 Paged result ordered by city then ZIP
400 { "error": "city is mandatory" }

Example

curl "$BASE_URL/geo/cities/search?city=abano&country_code=IT"

{
    "count": 1,
    "limit": 100,
    "offset": 0,
    "rows": [
        {
            "catastral_code": "A001",
            "city": "Abano Terme",
            "country_code": "IT",
            "province": "Padova",
            "province_code": "PD",
            "region": "Veneto",
            "region_code": 5,
            "zip": "35031"
        }
    ],
    "total": 1
}

GET /geo/cities/belfiore/:id

Returns cities matching a catastral (Belfiore) code, ordered by ZIP.

Path parameters

Parameter Required Description
id yes Belfiore code (case-insensitive).

Responses

Status Body
200 { "count": n, "rows": [...] }
400 { "error": "id is mandatory" }
404 { "error": "catastral code not found" }

Example

curl "$BASE_URL/geo/cities/belfiore/A182"

{
    "count": 2,
    "rows": [
        {
            "catastral_code": "A182",
            "city": "Alessandria",
            "country_code": "IT",
            "province": "Alessandria",
            "province_code": "AL",
            "region": "Piemonte",
            "region_code": 1,
            "zip": "15121"
        },
        {
            "catastral_code": "A182",
            "city": "Alessandria",
            "country_code": "IT",
            "province": "Alessandria",
            "province_code": "AL",
            "region": "Piemonte",
            "region_code": 1,
            "zip": "15122"
        }
    ]
}

GET /geo/zips/:zip

Returns the cities matching a ZIP code.

Path parameters

Parameter Required Description
zip yes ZIP code; leading zeros are preserved.

Responses

Status Body
200 { "count": n, "rows": [...] }
400 { "error": "zip is mandatory" }
404 { "error": "zip not found" }

Example

curl "$BASE_URL/geo/zips/35031"

{
    "count": 1,
    "rows": [
        {
            "catastral_code": "A001",
            "city": "Abano Terme",
            "country_code": "IT",
            "province": "Padova",
            "province_code": "PD",
            "region": "Veneto",
            "region_code": 5,
            "zip": "35031"
        }
    ]
}

GET /geo/regions

Returns the distinct regions, optionally restricted to a country.

Query parameters

Parameter Required Description
country_code no Restrict to this country.

Example

curl "$BASE_URL/geo/regions?country_code=IT"

{
    "count": 20,
    "rows": [
        { "region": "Abruzzo", "region_code": 13 },
        { "region": "Basilicata", "region_code": 17 },
        { "region": "Calabria", "region_code": 18 }
    ]
}

(The example is truncated; the real response contains all 20 Italian regions.)

GET /geo/provinces

Returns the distinct provinces, optionally restricted to a region.

Query parameters

Parameter Required Description
region_code no Restrict to this region code.

Example

curl "$BASE_URL/geo/provinces?region_code=5"

{
    "count": 7,
    "rows": [
        { "province": "Belluno", "province_code": "BL" },
        { "province": "Padova", "province_code": "PD" },
        { "province": "Rovigo", "province_code": "RO" },
        { "province": "Treviso", "province_code": "TV" },
        { "province": "Venezia", "province_code": "VE" },
        { "province": "Verona", "province_code": "VR" },
        { "province": "Vicenza", "province_code": "VI" }
    ]
}

← Back to the test console