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:

Parameter	Description	Values
country	Country code (Alpha-2 code).	LV - Latvia LT - Lithuania EE - Estonia
city	Populated place (city, town, village), administrative or teritorial unit.
street	Street name. If an address isn't split by its elements, you can pass full string here.
housenumber	House number or name.
postalcode	Postal code.
maxresults	Max results. You can get up to 25 results.

Response parameters

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

MatchScore object

Parameter	Description
Score	Match level score (from 0 to 100).
MatchLevel	Match level as following categories, "houseNumber", "city", "street", "district" (see Address object).

Location object

Parameter	Description
MapLocationId	Unique code of the returned location.
LocationType	Location type.

DisplayCoordinate object

Returns the WGS coordinates of the address point.

Parameter	Description
Latitude	Latitude coordinate in the WGS-84 projection (EPSG:4326).
Longitude	Longitude coordinate in the WGS-84 projection (EPSG:4326).

NavigationCoordinate object

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

Parameter	Description
Latitude	Latitude coordinate in the WGS-84 projection (EPSG:4326)
Longitude	Longitude coordinate in the WGS-84 projection (EPSG:4326).

Address object

Parameter	Description
Label	Full address.
Country	Country code (LV - Latvia, LT - Lithuania, EE - Estonia).
County	Administrative unit.
District	Territorial unit. Returns empty if matches city name (like Cēsis and Cēsu pilsēta).
City	Populated place (city, town, village).
Street	Street name or house name (if the address lacks the street element)
HouseNumber	House number or name if the address has a street name.
PostalCode	Postal code.

Error codes

Code	Description
400	Wrong input data.
404	No location found.
5xx	Server error.

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>