Search API

MAPCAT Search API is used to run full text search queries on our map database.

You can find a detailed description of the request parameters and the response scheme of the API point in our swagger documentation.

To access this API, you will need to use your Search API key.

Example

Here is a simple javascript example below showing how to use our Search API from browser:

var req = new XMLHttpRequest();
var reqListener = function(e) {
    console.log(req.response); // logging the search response to the console
};
req.addEventListener('load', reqListener);
req.open('GET', 'https://api.mapcat.com/location/search?query=Manhattan', true);
req.setRequestHeader('X-Api-Key', '< Your MAPCAT Search API key >');
req.send(null);

Parameters

  • query: this parameter is mandatory. It is a free form text you would like to search for. It can be a full address, a part of an address. Examples:

    • "denmark"
    • "Burgos España"
    • "Sweetwater Tavern Boylston Place Boston"
    • "Oudezijds Voorburgwal 146 Amsterdam, Nederland"

      As you can see, you can search in any language and our search engine is not case sensitive. The order of the address parts does not matter in the search text, so searching for "Hungary Budapest" and "Budapest Hungary" gives the same result.

  • lang is the language parameter. It is the two-letter (ISO 639-1) code of the language we want to retrieve the search results in. Examples:

    • "en": English
    • "de": German
    • "zh": Chinese

      When omitted, the default language of the map element is used for each search result.

  • lat and lng are optional parameters. They represent the latitude and longitude of the center of the viewport respectively. The viewport center is used as a hint in the sorting phase of the search results. Places closer to the geo-coordinates of the viewport center get a higher rank, thus more likely to appear before other results in the list.
  • bbox: this parameter is also optional. It represents the viewport bounding box. Currently it requires the lat and lng parameters to be set. It defines the top left and bottom right geo-coordinates for the search viewport, and it is also used as a hint in the sorting phase. Found items inside the bounding box are getting higher ranks.

Response

The search response is a json object. It consists of two parts: meta and result.

In case of error, only meta is specified, and result is null. Meta has 3 fields: status_code, message and version. Parameter status_code represents the http status code, message is a detailed error message, and version is the version of the search engine.

When there was no error during the search request, field result is specified. It is an array, containing the search results. They are ordered starting with the most relevant hit. The elements of the array are objects having the following fields:

  • type is a string field representing the type of the search item. It can be
    • "STR" (street)
    • "POI" (point-of-interest)
    • "SHP" (shape)
    • "COS" (center-of-settlement or center-of-structure)
    • "ADR" (address)
  • address is an object. It contains the full address of the search result as a formed text field, and the address parts of the search hit in a categorized way (e.g.: country, state, city, district...). For a full list of address parts, look up our swagger documentation.
  • poi in case the found item is of type POI, the name, OSM id (osmidx) and geolocation (pos) are given in this object.
  • geometry: this object field contains the geometry information of the search hit. It has the following fields: geometry, position, tl and br. Geometry is specified for street ("STR") results only. It contains the geometry of the street in GeoJSON format. Position is the center point of the object. Fields tl and br are representing the top left and bottom right coordinates of the bounding box of the search hit, respectively. This bounding box can be used for e.g. moving the view over the specified area.