Extended geocoding

Extended geocoding returns address information and coordinates from the queried text (address) string. Unlike the standard geocoding, the API gives greater importance to postal code for ordering of results, returns match score value of the returned and allows the address to be entered as separate elements (however, it's not mandatory). To increase the chance of getting results, a multi-level approach is being used in the backend, if the first step is unsuccesful, the geocoder becomes less strict at the next steps. If it's impossible to get correct address, only the location of the populated place might be returned.

Only Baltics' addresses can be geocoded. The official Latvian, Estonian and Lithuanian address databases are being used as the data source. Navigation coordinates of the closest point of the routable road network for motor vehicles are calculated using the Jāņa sēta road network.

API URL

The request URL should match the following pattern:

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

The response is given in XML.

The HTTP GET request method is used.

Query parameters

The request consists of the following GET parameters:

Response parameters

The response consists of an array of objects. See below the description of each object.

MatchScore object

Location object

DisplayCoordinate object

Returns the WGS coordinates of the address point.

NavigationCoordinate object

Returns the WGS coordinates of the nearest point on the road network to the returned address point.

Address object

Error codes

Examples

Input:

https://api.kartes.lv/v3//ext-geocoding?city=Rīga&postalcode=1020&street=Krasta%20iela&housenumber=105A&maxresults=1

Output:

<LocationMatch>
<Matching>
    <Score>93</Score>
    <MatchLevel>houseNumber</MatchLevel>
<MatchingScore>
    <City>93</City>
    <Street>93</Street>
    <HouseNumber>93</HouseNumber>
    <Country>100</Country>
</MatchingScore>
<MatchType>pointAddress</MatchType>
</Matching>
<Location>
    <MapLocationId>89ada520023eb349957e9e4a93f2270b</MapLocationId>
    <LocationType>address</LocationType>
<DisplayCoordinate>
    <Latitude>56.921337</Latitude>
    <Longitude>24.168581</Longitude>
</DisplayCoordinate>
<NavigationCoordinate>
    <Latitude>56.921178</Latitude>
    <Longitude>24.168718</Longitude>
</NavigationCoordinate>
<Address>
    <Label>Krasta iela 105A, Rīga, Latgales priekšpilsēta, Latvija</Label>
    <Country>LV</Country>
    <County>Rīga</County>
    <City>Rīga</City>
    <District>Latgales priekšpilsēta</District>
    <Street>Krasta iela</Street>
    <HouseNumber>105A</HouseNumber>
    <PostalCode>1019</PostalCode>
    <AdditionalData key="CountryName">Latvija</AdditionalData>
    <AdditionalData key="CountyName">Rīga</AdditionalData>
</Address>
</Location>
</LocationMatch>

Input with the queried string as a single parameter and partially correct postal code:

https://api.kartes.lv/v3//ext-geocoding?street=daugavpils%20%2022%20sloka&postalcode=2020&maxresults=1

Output:

<LocationMatch>
<Matching>
<Score>93</Score>
    <MatchLevel>houseNumber</MatchLevel>
    <MatchingScore>
        <City>93</City>
        <Street>93</Street>
        <HouseNumber>93</HouseNumber>
        <Country>100</Country>
    </MatchingScore>
    <MatchType>pointAddress</MatchType>
</Matching>
<Location>
<MapLocationId>c3f402b02256bea19c0a3bd68a34916b</MapLocationId>
<LocationType>address</LocationType>
<DisplayCoordinate>
    <Latitude>56.942235</Latitude>
    <Longitude>23.608701</Longitude>
</DisplayCoordinate>
<NavigationCoordinate>
    <Latitude>56.942152</Latitude>
    <Longitude>23.608809</Longitude>
</NavigationCoordinate>
<Address>
    <Label>Daugavpils iela 22, Jūrmala, Latvija</Label>
    <Country>LV</Country>
    <County>Jūrmala</County>
    <City>Jūrmala</City>
    <District/>
    <Street>Daugavpils iela</Street>
    <HouseNumber>22</HouseNumber>
    <PostalCode>2011</PostalCode>
    <AdditionalData key="CountryName">Latvija</AdditionalData>
    <AdditionalData key="CountyName">Jūrmala</AdditionalData>
</Address>
</Location>
</LocationMatch>

Use examples

Defining an extended geocoding API class in JavaScript code:

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

    // Method to fetch extended geocoded data
    async getExtendedGeocodingData({city, postalcode, street, housenumber, maxresults = 1}) {
        const params = new URLSearchParams({
            city: city,
            postalcode: postalcode,
            street: street,
            housenumber: housenumber,
            maxresults: maxresults
        });

        const url = `${this.baseUrl}/${this.apiKey}/ext-geocoding?${params.toString()}`;

        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 extended geocoding API class:

const api = new ExtendedGeocodingAPI();

api.getExtendedGeocodingData({city: 'Rīga', postalcode: '1020', street: 'Krasta iela', housenumber: '105A', maxresults = 1})
    .then(result => {
        if (!result.success) {
            console.error('Error:', result.error); // Handle the error
            return;
        }

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