Search API
The Search API with autocomplete. It can be also used as a less strict geocoder.
API URL
The request URL should match the following pattern:
https://api.kartes.lv/v3//search?
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 |
|---|---|---|
| q | String query. | Mandatory |
| layers | Object categories (comma separated) | |
| iso_code | Country (LVA for Latvia, EST for Estonia, LTU for Lithuania) | LVA, EST, LTU |
| format | Response format (JSON or GeoJSON). |
|
| geometry | Full geometry | Without value |
| fields | Fields that should be included in the response (comma separated). | Mandatory
|
| cs | Coordinate system (an optional parameter). By default, the WGS-84 (EPSG:4326) coordinates are used. The parameter allows to set other CRS. |
|
| limit | Max ojects in any layer. | From 1 to 50 (default value) |
| pop_place_level | Search in cities only (only for addresses). |
|
| address_code | The official address code (only for addresses). | Example: 105747812 |
| magicKey | The hash code (only for addresses). | |
| region | One or more administrative units (e.g., parish, municipality, district), separated by commas. It's possible to define the region also from a WKT polygon. (only for addresses) | Examples: Cēsu novadsCentra rajons, Latgales priekšpilsētaAukštelkų seniūnijaPõlva vald'POLYGON ((24.25309903890031 57.01492713579236, 24.261838178785016 56.841545957617114, 23.963459524961085 56.83369239854119, 23.934745262080735 57.008809515780456, 24.25309903890031 57.01492713579236))' |
| post | Searches only into areas with specified postal codes (only for addresses). Example: LV-1021,LV-1050 |
|
| postGroups | Searches only into areas with specified postal code groups (only for addresses). Example: LV-10,LV-54 |
Object categories (layers)
- adrese - addresses,
- historical_address - historical addresses,
- apdz_vieta - populated places (cities, towns, villages),
- admin_vien - administrative units,
- terit_vien - territorial units,
- historical_address - historical addresses,
- iela - streets (names) and roads (national route numbers, names),
- river - rivers and canals,
- lake - lakes and other water bodies,
- mountain - hills,
- swamp - wetlands,
- island - islands,
- park_forest - parks or forests,
- nature - nature sightseeing objects,
- protected_area - conservation areas,
- public_institution - public institutions, companies
- finance - banks and financial companies,
- catering - restaurants, bars, fast food etc,
- hotels - hotels and other accommodation establishments,
- fuel - fuel, LNG and charging stations,
- education - education institutions,
- health_care - hospitals and medical establishments,
- religion - churches and other religious sites,
- sport_recreation - sport and recreation sites,
- culture - cultural institutions,
- shopping - shopping malls and other stores,
- tourism - tourist attractions,
- transport - public transport objects,
- cadastral - cadastral parcels,
- cadastral_building - cadastral buildings,
- organization - organizations or companies (data from Register of Enterprises).
Response parameters
The response consists of all queried data categories having an array of objects with parameters defined by the fields parameter.
Error codes
| Status code | Description |
|---|---|
| 404 | No location found. The URL is not recognized; the resource does not exist. |
| 5xx | Server error. |
Examples
Address search
Input:
https://api.kartes.lv/v3//search?q=krasta%20105%20riga&layers=adrese&cs=wgs84&fields=name,maja,iela,pop_place,terit_vien,admin_vien,iso_code,index,x,y
Response:
{
"adrese": [
{
"name": "Krasta iela 105, Rīga, Latgales pr-pilsēta, Latvija",
"maja": "105",
"iela": "Krasta iela",
"pop_place": "Rīga",
"terit_vien": "Latgales priekšpilsēta",
"admin_vien": "Rīga",
"iso_code": "LVA",
"index": "LV-1019",
"x": 24.16781,
"y": 56.921167
},
{
"name": "Krasta iela 105A, Rīga, Latgales pr-pilsēta, Latvija",
"maja": "105A",
"iela": "Krasta iela",
"pop_place": "Rīga",
"terit_vien": "Latgales priekšpilsēta",
"admin_vien": "Rīga",
"iso_code": "LVA",
"index": "LV-1019",
"x": 24.168581,
"y": 56.921337
}
]
}
Other
Input:
https://api.kartes.lv/v3//search?q=rododendru%20iela%20rīga&layers=iela&cs=wgs84&fields=name,pop_place,iso_code,x_min,y_min,x_max,y_max,x_first,y_first,the_geom
Response:
{
"iela": [
{
"name": "Rododendru iela",
"pop_place": "Rīga",
"iso_code": "LVA",
"x_min": "24.047660",
"y_min": "56.947559",
"x_max": "24.054698",
"y_max": "56.949043",
"x_first": "24.054698",
"y_first": "56.949043",
"the_geom": "{\"type\":\"LineString\",\"coordinates\":[[24.054698,56.949043],[24.054496,56.949013],[24.054241,56.948963],[24.054123,56.948921],[24.053951,56.94885],...}"
}
]
}
Input:
https://api.kartes.lv/v3//search?q=berlīne&cs=wgs84&format=geojson&fields=name,pop_place,iso_code,x_min,y_min,x_max,y_max,x_first,y_first,the_geom
Response:
{
"apdz_vieta": {
"type": "FeatureCollection",
"name": "apdz_vieta",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"adrese": {
"type": "FeatureCollection",
"name": "adrese",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
26.328814,
56.977481
]
},
"properties": {
"name": "Berlīne, Cesvaines pag., Madonas nov., Latvija",
"iso_code": "LVA"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
25.668572,
57.19281
]
},
"properties": {
"name": "Berlīne, Dzērbene, Dzērbenes pag., Cēsu nov., Latvija",
"pop_place": "Dzērbene",
"iso_code": "LVA"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
26.606173,
56.826337
]
},
"properties": {
"name": "Berlīne, Meirāni, Indrānu pag., Madonas nov., Latvija",
"pop_place": "Meirāni",
"iso_code": "LVA"
}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
24.946032,
57.347814
]
},
"properties": {
"name": "Berlīne, Straupe, Straupes pag., Cēsu nov., Latvija",
"pop_place": "Straupe",
"iso_code": "LVA"
}
}
]
},
"admin_vien": {
"type": "FeatureCollection",
"name": "admin_vien",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"terit_vien": {
"type": "FeatureCollection",
"name": "terit_vien",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"iela": {
"type": "FeatureCollection",
"name": "iela",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": [
{
"type": "Feature",
"geometry": {
"type": "MultiLineString",
"coordinates": [
[
[
24.820069,
56.534862
],...
],...
]
},
"properties": {
"name": "Berlīnes ceļš",
"iso_code": "LVA",
"x_min": "24.820069",
"y_min": "56.523434",
"x_max": "24.826498",
"y_max": "56.534862",
"x_first": "24.820069",
"y_first": "56.534862"
}
},
{
"type": "Feature",
"geometry": {
"type": "MultiLineString",
"coordinates": [
[
[
24.616246,
56.894385
],...
],...
},
"properties": {
"name": "Berlīnes līnija",
"iso_code": "LVA",
"x_min": "24.616246",
"y_min": "56.893761",
"x_max": "24.687871",
"y_max": "56.908783",
"x_first": "24.616246",
"y_first": "56.894385"
}
}
]
},
"river": {
"type": "FeatureCollection",
"name": "river",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"lake": {
"type": "FeatureCollection",
"name": "lake",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"mountain": {
"type": "FeatureCollection",
"name": "mountain",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"cadastral": {
"type": "FeatureCollection",
"name": "cadastral",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"cadastral_building": {
"type": "FeatureCollection",
"name": "cadastral_building",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"hotels": {
"type": "FeatureCollection",
"name": "hotels",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"fuel": {
"type": "FeatureCollection",
"name": "fuel",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"education": {
"type": "FeatureCollection",
"name": "education",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"religion": {
"type": "FeatureCollection",
"name": "religion",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"culture": {
"type": "FeatureCollection",
"name": "culture",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"shopping": {
"type": "FeatureCollection",
"name": "shopping",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"nature": {
"type": "FeatureCollection",
"name": "nature",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
25.3277100919886,
57.3563960998154
]
},
"properties": {
"name": "Berlīne",
"iso_code": "LVA"
}
}
]
},
"catering": {
"type": "FeatureCollection",
"name": "catering",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"finance": {
"type": "FeatureCollection",
"name": "finance",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"health_care": {
"type": "FeatureCollection",
"name": "health_care",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"public_institution": {
"type": "FeatureCollection",
"name": "public_institution",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"sport_recreation": {
"type": "FeatureCollection",
"name": "sport_recreation",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"tourism": {
"type": "FeatureCollection",
"name": "tourism",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
24.1041293486792,
56.9585196144391
]
},
"properties": {
"name": "Berlīnes mūra fragments",
"pop_place": "Rīga",
"iso_code": "LVA"
}
}
]
},
"transport": {
"type": "FeatureCollection",
"name": "transport",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"swamp": {
"type": "FeatureCollection",
"name": "swamp",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"island": {
"type": "FeatureCollection",
"name": "island",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"park_forest": {
"type": "FeatureCollection",
"name": "park_forest",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"protected_area": {
"type": "FeatureCollection",
"name": "protected_area",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": []
},
"historical_address": {
"type": "FeatureCollection",
"name": "historical_address",
"crs": {
"type": "name",
"properties": {
"name": "urn:ogc:def:crs:EPSG::4326"
}
},
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
25.668572,
57.19281
]
},
"properties": {
"name": "Berlīne, Dzērbenes pag., Cēsu raj., Latvija",
"iso_code": "LVA"
}
}
]
}
}
Use example
Defining a search API class in JavaScript code:
class SearchApi {
constructor() {
this.apiKey = 'your_api_key_here'; // Replace with your actual API key
this.baseUrl = 'https://api.kartes.lv/v3';
}
// Method to perform the search
async search(query) {
const searchParams = new URLSearchParams({
q: query,
layers: 'adrese',
cs: 'wgs84',
fields: 'name,maja,iela,pop_place,terit_vien,admin_vien,iso_code,index,x,y'
});
const url = `${this.baseUrl}/${this.apiKey}/search?${searchParams.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 search API class:
const api = new SearchAPI('your_api_key'); // Replace with your actual API key
const query = 'krasta 105a riga';
api.search(query)
.then(result => {
if (!result.success) {
console.error('Error:', result.error); // Handle the error
return;
}
console.log(result.data);
// Use the data
});