Skip to content

Retrieving towns by town name

Description

Retrieving towns by town name. Only a part of the name can be specified.

URL structure

GET /v2/references/towns/by/name

List of parameters

Name Description Parameter transfer type Required(+)/Default(value)
language Localization language. Usage details. Query string parameter ru
areaIds Additionally: array of region ids. Use restriction: this parameter is taken into account only if at least one value is specified in the countrySigns parameter. Effect: the fetch will contain only the towns whose regions are specified as the value of this parameter. Query string parameter
countrySigns Additionally: array of country codes in the format ISO 3166-1 alpha-2. Effect: the fetch will contain only the towns whose countries are specified as the value of this parameter. Query string parameter
excludeCountrySigns Additionally: array of country codes in the format ISO 3166-1 alpha-2. Use restriction: this parameter is taken into account only if no value is specified in the countrySigns parameter. Effect: the fetch will contain only the towns whose countries are not specified as the value of this parameter. Query string parameter
limit The desired number of responses, the maximum is 100. Query string parameter 10
query Name or part of a name. Query string parameter +

Result

Array of structures "Town".

Samples of requests and responses

query 
curl -X GET -H "Accept: application/json" -H "Authorization: 3WQ1EQ465C4005000130" "https://api.lardi-trans.com/v2/references/towns/by/name?language=uk&query=kras&limit=5"

[
    {
        "id": 1511,
        "name": "Красноярськ",
        "countrySign": "RU",
        "areaId": 74,
        "lat": 56.008711,
        "lon": 92.870412,
        "postcode": [
            "660000"
        ]
    },
    {
        "id": 578,
        "name": "Краснодар",
        "countrySign": "RU",
        "areaId": 73,
        "lat": 45.034942,
        "lon": 38.976032
    },
    {
        "id": 89,
        "name": "Красноперекопськ",
        "countrySign": "UA",
        "areaId": 25,
        "lat": 45.952198,
        "lon": 33.795077,
        "postcode": [
            "96000-96005"
        ]
    },
    {
        "id": 4337,
        "name": "Краснопілля",
        "countrySign": "UA",
        "areaId": 32,
        "lat": 50.767108,
        "lon": 35.267666,
        "postcode": [
            "42400"
        ]
    },
    {
        "id": 6529,
        "name": "Краснокутськ",
        "countrySign": "UA",
        "areaId": 34,
        "lat": 50.055979,
        "lon": 35.147628
    }
]
query + countrySigns 
curl -X GET -H "Accept: application/json" -H "Authorization: 3WQ1EQ465C4005000130" "https://api.lardi-trans.com/v2/references/towns/by/name?language=uk&query=kras&countrySigns=PL"

[
    {
        "id": 5616,
        "name": "Краснистав",
        "countrySign": "PL",
        "areaId": 149,
        "lat": 50.982614,
        "lon": 23.172465,
        "postcode": [
            "22-300"
        ]
    },
    {
        "id": 113339,
        "name": "Красеюв",
        "countrySign": "PL",
        "areaId": 154,
        "lat": 50.668569,
        "lon": 18.248019,
        "postcode": [
            "46-040"
        ]
    }
]
query + countrySigns + areaIds 
curl -X GET -H "Accept: application/json" -H "Authorization: 3WQ1EQ465C4005000130" "https://api.lardi-trans.com/v2/references/towns/by/name?language=uk&query=kras&countrySigns=UA&areaIds=34"

[
    {
        "id": 6529,
        "name": "Краснокутськ",
        "countrySign": "UA",
        "areaId": 34,
        "lat": 50.055979,
        "lon": 35.147628
    },
    {
        "id": 72,
        "name": "Красноград",
        "countrySign": "UA",
        "areaId": 34,
        "lat": 49.373049,
        "lon": 35.461353,
        "postcode": [
            "63300"
        ]
    },
    {
        "id": 68,
        "name": "Краснопавлівка",
        "countrySign": "UA",
        "areaId": 34,
        "lat": 49.137419,
        "lon": 36.3239,
        "postcode": [
            "64622"
        ]
    },
    {
        "id": 131706,
        "name": "Краснопавлівське",
        "countrySign": "UA",
        "areaId": 34,
        "lat": 49.21291,
        "lon": 36.297798,
        "postcode": [
            "64143"
        ]
    },
    {
        "id": 122810,
        "name": "Красне Перше",
        "countrySign": "UA",
        "areaId": 34,
        "lat": 49.943676,
        "lon": 37.755707,
        "postcode": [
            "62710"
        ]
    }
]
query + excludeCountrySigns 
curl -X GET -H "Accept: application/json" -H "Authorization: 3WQ1EQ465C4005000130" "https://api.lardi-trans.com/v2/references/towns/by/name?language=uk&query=kras&excludeCountrySigns=UA,RU,PL"

[
    {
        "id": 4868,
        "name": "Красне",
        "countrySign": "BY",
        "areaId": 127,
        "lat": 52.679631,
        "lon": 24.363496
    },
    {
        "id": 114805,
        "name": "Красен",
        "countrySign": "BG",
        "areaId": 0,
        "lat": 43.74045,
        "lon": 25.98316
    }
]