Geocoding API

The API gives the coordinates and full address information of the given address string.

API URL

The request URL should match the following pattern:

https://api.kartes.lv/v3//geocoding?

By default, the response is given in JSON (JSONP and XML are also available).

The HTTP GET request method is used.

Query parameters

The request consists of the following GET parameters:

Parameter	Description	Possible values
address	Address or hash string.	Mandatory, if address_code not used
address_code	Address code.	Mandatory, if address not used
limit	Maximum number of returned results.	From 1 to 25 (default value).
LVA	Use it if the API should search only in Latvia.
result_data_type	Output format. JSON is the default option.	json (default value) jsonp xml
callback	Callback function	Valid if result_data_type=jsonp.
historical	Historical addreses	If parameter not present search current addresses. If paremeter value is not present serch in historical addresses if cannot find current addresses. If parameter value is only return only historical addresses.
strict	Strict search	1

Response parameters

The response consists of the following parameters.

Parameter	Description
rank	Rank of address.
gid	Unique ID.
valsts	Country name.
admin_vien	Administrative unit.
terit_vien	Territorial unit.
apdz_vieta	Populated place (city, town or village)
iela	Street name.
maja	House name or number.
index	Postal code.
korpuss	Building block number.
x	x-coordinate in the TM Baltic93 CRS (EPSG:25884).
y	y-coordinate in the TM Baltic93 CRS (EPSG:25884).
address_hash	Hash of address.
iso_code	Country ISO code.
vzd_id	Code of address.
lat	Latitude coordinate in the WGS-84 projection (EPSG:4326).
lon	Longitude coordinate in the WGS-84 projection (EPSG:4326).
adrese	Full address.

Error codes

Status code	Description
200	Wrong input data. Server can’t respond due to client error.
404	No location found. The URL is not recognized; the resource does not exist.
5xx	Server error.

Examples

Input:

https://api.kartes.lv/v3//geocoding?address=Brīvības&limit=1

Response:

[
    {
        "rank": "0.333333",
        "gid": "487606023",
        "valsts": "Latvija",
        "admin_vien": "Ventspils",
        "terit_vien": "Ventspils pilsēta",
        "apdz_vieta": "Ventspils",
        "iela": "Brīvības iela",
        "maja": "1A",
        "index": "LV-3601",
        "korpuss": "",
        "x": "354278.323000",
        "y": "6364308.441998",
        "address_hash": "cae33907edc0cdb37093b83db1bc14b8",
        "iso_code": "LVA",
        "vzd_id": "106279496",
        "lat": 57.398171,
        "lon": 21.574947,
        "adrese": "Brīvības iela 1A, Ventspils, Latvija"
    }
]

Use examples

Defining a geocoding API class in JavaScript code:

class GeocodingApi {
    constructor() {
        this.apiKey = 'your_api_key_here'; // Replace with your actual API key
        this.baseUrl = 'https://api.kartes.lv/v3';
    }

    // Method to fetch geocoded data
    async getGeocodingData(address, limit = 1) {
        const url = `${this.baseUrl}/${this.apiKey}/geocoding?address=${encodeURIComponent(address)}&limit=${limit}`;

        try {
            const response = await fetch(url);

            // Check if the response is ok (status code 200-299)
            if (!response.ok) {
                throw new Error(`Error fetching data: ${response.statusText}`);
            }

            const data = await response.json();
            return { success: true, data };
        } catch (error) {
            console.error('Fetch error:', error);
            return { success: false, error: error.message };
        }
    }
}

Using the geocoding API class:

const api = new GeocodingAPI();

api.getGeocodingData('Brīvības')
    .then(result => {
        if (!result.success) {
            console.error('Error:', result.error); // Handle the error
            return;
        }

        console.log(result.data);
        // Use the data
    });