Reverse geocoding

The API finds an address based on given coordinates.

API URL

The request URL should match the following pattern:

https://api.kartes.lv/v3//reverse_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
x	x-coordinate in the TM Baltic93 CRS (EPSG:25884).	Mandatory, if lat, lon not used
y	y-coordinate in the TM Baltic93 CRS (EPSG:25884).	Mandatory, if lat, lon not used
lat	Latitude coordinate in the WGS-84 projection (EPSG:4326)	Mandatory, if x, y not used
lon	Longitude coordinate in the WGS-84 projection (EPSG:4326)	Mandatory, if x, y not used
latlon	latlon coordinates in the WGS-84 projection (EPSG:4326).	Format 57.208140,24.773591. Mandatory if type = suggest_place
returnTerritUnitAfter	If this parameter is used, only territorial unit and administrative unit is returned. The minimum distance in meters, when this approach should work, should be defined.	Meters (valid if type=address)
result_data_type	Output format. JSON is the default option.	json jsonp xml
callback	Callback function	Valid if result_data_type=jsonp.
type	The type of object searched for	Possible values: address (default value) populated_area country suggest_place admin_unit (administrative unit) territ_unit (territorial unit) cadastral (cadastral data)
limit	Number of returned addresses.	From 1 (default value) to 20. Valid if type=address
short_address	Short address.	Without value. Working as type=address, ignore type parameter

Response parameters depending of type

type = address

The response consists of a single or multiple elements. It has following parameters:

Parameter	Description
valsts	Country.
admin_vien	Administrative unit.
terit_vien	Territorial unit.
apdz_vieta	Populated place (city, town or other settlement).
iela	Street or road name.
maja	House number or name.
index	Postal code.
vzd_id	The unique address identifier.
distance	Distance in meters from the given point to the returned address.
x	x-coordinate in the TM Baltic93 CRS (EPSG:25884) of the address.
y	y-coordinate in the TM Baltic93 CRS (EPSG:25884) of the address.
lon	Longitude coordinate in the WGS-84 projection (EPSG:4326) of the address.
lat	Latitude coordinate in the WGS-84 projection (EPSG:4326) of the address.
adrese	Full (or short if short_address) address.

type = populated_area

The response consists of a single elements. It has following parameters:

Parameter	Description
name	Name.
iso_code	Country ISO code.
dist	Distance (meters).
country_name	Countru name.

type = country

The response consists of a single elements. It has following parameters:

Parameter	Description
country	Countru name.

type = suggest_place

The response consists of a single or multiple elements. Answer is the same as type = address and one more parameter:

Parameter	Description
suggestion	Suggested address.

type = admin_unit

The response consists of a single elements. It has following parameters:

Parameter	Description
admin_unit	Administrative unit.
iso_code	Country ISO code.
country	Countru name.

type = territ_unit

The response consists of a single elements. It has following parameters:

Parameter	Description
territ_unit	Territorial unit.
admin_unit	Administrative unit.
iso_code	Country ISO code.
country	Countru name.

type = cadastral

The response consists of a single elements. It has following parameters:

Parameter	Description
code	Cadastre number.
ownership_status	Ownership status.

Error codes

Status code	Description
200	Wrong coords.
200	Wrong type.
200	Parameter latlon expected.
200	Wrong coordinates or not delimited by comma.
404	No location found. The URL is not recognized; the resource does not exist.
5xx	Server error.

Examples

Input:

https://api.kartes.lv/v3//reverse_geocoding?x=509679&y=6314169

Response:

{
  "valsts": "Latvija",
  "admin_vien": "Rīga",
  "terit_vien": "Vidzemes priekšpilsēta",
  "apdz_vieta": "Rīga",
  "iela": "Brīvības gatve",
  "maja": "197A",
  "index": "LV-1039",
  "korpuss": "",
  "vzd_id": "101867023",
  "distance": 25,
  "x": "509679.56",
  "y": "6314193.80",
  "lon": 24.159217,
  "lat": 56.971222,
  "adrese": "Brīvības gatve 197A, Rīga, Vidzemes pr-pilsēta, Latvija"
}

Input:

https://api.kartes.lv/v3//reverse_geocoding?lat=57.208140&lon=24.773591

Response:

{
  "valsts": "Latvija",
  "admin_vien": "Siguldas novads",
  "terit_vien": "Krimuldas pagasts",
  "apdz_vieta": "",
  "iela": "",
  "maja": "Akmeņi",
  "index": "LV-2144",
  "korpuss": "",
  "vzd_id": "104910650",
  "distance": 99,
  "x": "546816.85",
  "y": "6340771.40",
  "lon": 24.775007,
  "lat": 57.207688,
  "adrese": "Akmeņi, Krimuldas pag., Siguldas nov., Latvija"
}

Use examples

Defining a reverse geocoding API class in JavaScript code:

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

    // Method to fetch reverse geocoded data by latitude and longitude
    async getReverseGeocodingData(lat, lon) {
        const url = `${this.baseUrl}/${this.apiKey}/reverse_geocoding?lat=${lat}&lon=${lon}`;

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

const api = new ReverseGeocodingAPI();

api.getReverseGeocodingData(57.208140, 24.773591)
    .then(result => {
        if (!result.success) {
            console.error('Error:', result.error); // Handle the error
            return;
        }

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