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 the parameter is omitted, only current addresses are searched. If provided without a value, current addresses are searched first, then historical addresses if no results are found. If set to only, only historical addresses are searched.
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.

Status 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
    });