Documentation
Geocoding, Search & Autocomplete, Static maps
Geocoding
Geocoding is the process of converting addresses—such as “Residenzstraße 1, 80333 München”—into geographical coordinates: latitude 48.1417088 and longitude 11.5772990. This process is accomplished using the Search API. Additionally, reverse geocoding allows for the conversion of geographical coordinates into corresponding address information. By using the Address Lookup, detailed information about a specific location can be retrieved.
Search API
Endpoint
https://api.gdpr-map.eu/search?[PARAMETER]&key=[API_KEY]The search term can be provided in two different forms: unstructured or structured.
Unstructured Search
Unstructured search queries are processed from left to right initially, and if that fails, from right to left. This allows you to search for both “Residenzstraße 1, München” and “München, Residenzstraße 1”. Commas are optional but enhance performance by reducing search complexity.
The unstructured form can also contain special expressions that describe the type of place to be returned or a coordinate to search near a specific location.
| Parameter | Value |
|---|---|
| q | Unstructured Search Term |
Example
https://api.gdpr-map.eu/search?q=Residenzstraße 1, München&key=[API_KEY]Structured Search
The structured form of the search query allows for looking up an address that is already divided into its components. Each parameter represents a field of the address. All parameters are optional. You should only use those relevant to the address you want to geocode.
This cannot be combined with the q parameter from the unstructured search.
| Parameter | Value |
|---|---|
| amenity | Name or Type of the POI |
| street | Street and House Number |
| city | City |
| county | County |
| state | Federal state |
| country | Country |
| postalcode | Postal Code |
Example
https://api.gdpr-map.eu/search?street=Residenzstraße 1&city=München&country=Deutschland&key=[API_KEY]Parameter
The following parameters can be used to further narrow down the search and modify the output. They can be used for both forms of the search query.
Output format
| Parameter | Value | Standard |
|---|---|---|
| format | One of: xml, json, jsonv2, geojson, geocodejson | jsonv2 |
| json_callback | Name of the callback function | not set |
| limit | A number from 1 to 40. | 10 |
The “format” parameter determines the output format.
The “json_callback” parameter is only relevant for JSON output formats. If specified, the JSON output will be wrapped in a callback function with the given name.
The maximum number of returned results can be limited by the “limit” parameter. It must not exceed 40.
Output details
| Parameter | Value | Standard |
|---|---|---|
| Address details | 0 or 1 | 0 |
| Extra tags | 0 or 1 | 0 |
| Name details | 0 or 1 | 0 |
If you want to break down the address into its components, set the “addressdetails” parameter to 1. The exact content of the address breakdown depends on the output format.
If you need additional information in the result that is available in the database, such as a Wikipedia link or opening hours, set “extratags” to 1.
If you are interested in the list of all known names, set “namedetails” to 1. This will also output older names, name variants, references, or brand names.
Output language
| Parameter | Value | Standard |
|---|---|---|
| accept-language | Browser language identifier | Content of the “Accept-Language” HTTP header |
Preferred language order for displaying search results. This can either be a simple comma-separated list of language codes or the same format as the “Accept-Language” HTTP header.
Limit output
There are two ways to influence the results. Filters completely exclude certain types of results. Boost parameters only change the order of the results, giving preference to some results over others.
| Parameter | Value | Standard |
|---|---|---|
| countrycodes | Comma-separated list of country codes | not set |
Filter that restricts the search results to one or more countries. The country code must correspond to the ISO 3166-1 alpha-2 code of the country, e.g., gb for the United Kingdom, de for Germany.
Each location is assigned a country code based on the OSM country boundaries. In rare cases, a location might not be within any country at all, for example, if it is in international waters. These locations are also excluded if the filter is set.
This parameter should not be confused with the ‘country’ parameter of the structured search. The ‘country’ parameter contains a search term and is treated fuzzily. The ‘countrycodes’ parameter is an exact filter and should therefore be preferred. Using both parameters in the same query works. If the parameters contradict each other, the search will return no results.
| Parameter | Value | Standard |
|---|---|---|
| featureType | One of: country, state, city, settlement | not set |
The “featureType” parameter allows for a finer selection of locations from the address layer. The results can be restricted to locations that form the ‘state’, ‘country’, or ‘city’ part of an address. A featureType of “settlement” selects any human-inhabited feature from ‘state’ down to ‘neighbourhood’.
| Parameter | Value | Standard |
|---|---|---|
| exclude_place_ids | Comma-separated list of place IDs | empty |
If you do not want certain OSM objects to appear in the search results, specify a comma-separated list of place IDs that you want to skip. This can be used to obtain additional search results. For example, if a previous query returned only a few results, including them here would cause the search to return other, less accurate matches (if possible).
| Parameter | Value | Standard |
|---|---|---|
| viewbox | not set |
Boost parameter that restricts the search to the specified area. Any two corners of the rectangle are accepted as long as they form a proper rectangle. Here, x stands for longitude and y stands for latitude.
| Parameter | Value | Standard |
|---|---|---|
| bounded | 0 or 1 | 0 |
When set to 1, this turns the ‘viewbox’ parameter (see above) into a filter parameter that excludes all results outside the viewbox.
When bounded=1 is specified and the viewbox is small enough, an exclusive amenities search is possible. Specify the particular amenity keyword in square brackets, e.g., [pub], and a selection of objects of this type will be returned. There is no guarantee that the result will include all objects in the area.
Output of polygons
| Parameter | Value | Standard |
|---|---|---|
| polygon_geojson | 0 or 1 | 0 |
| polygon_kml | 0 or 1 | 0 |
| polygon_svg | 0 or 1 | 0 |
| polygon_text | 0 or 1 | 0 |
Adds the complete geometry of the place to the output of the result. Output formats in GeoJSON, KML, SVG, or WKT are supported. Only one of these options can be used at a time.
| Parameter | Value | Standard |
|---|---|---|
| polygon_threshold | Floating point number | 0.0 |
When one of the polygon_* outputs is selected, a simplified version of the output geometry is returned. The parameter describes the tolerance in degrees by which the geometry may differ from the original geometry. The topology of the geometry is preserved.
Miscellaneous
| Parameter | Value | Standard |
|---|---|---|
| dedupe | 0 or 1 | 1 |
| debug | 0 or 1 | 0 |
Sometimes there are multiple objects in OSM that identify the same place or object. The simplest case is a street that is divided into many different OSM ways due to different attributes. Nominatim will attempt to recognize such duplicates and return only one match. Setting this parameter “dedupe” to 0 disables this deduplication mechanism and ensures that all results are returned.
The “debug” parameter outputs various developer debug information. This includes data about the internals of the “search loop” logic and SQL queries. The output is in HTML format, which overrides the specified machine-readable format.
Reverse Geocoding
Reverse geocoding generates an address from a coordinate given as latitude and longitude.
Die Reverse Geocoding API berechnet nicht die genaue Adresse der Koordinaten, sondern ermittelt das nächstgelegene OSM-Objekt und dessen Adressinformationen. Dies kann gelegentlich zu unerwarteten Ergebnissen führen.
Initially, only OSM objects suitable for the search are included. Small, unnamed paths, for example, are missing from the database and therefore cannot be used for reverse geocoding.
Another issue to consider is that the nearest OSM object may not always have a similarly matching address to the requested coordinate. For example, in densely built-up urban areas, it may belong to a completely different street.
Endpoint
https://api.gdpr-map.eu/reverse?lat=[latitude]&lon=[longitude]&[PARAMETER]&key=[API_KEY]The parameters “latitude” and “longitude” correspond to the latitude and longitude of a coordinate in the WGS84 projection. The API returns exactly one result or an error if the coordinate is in an area without OSM data coverage.
Example
https://api.gdpr-map.eu/reverse?lat=48.1417088&lon=11.5772990&key=[API_KEY]Parameter
This section lists additional parameters to further influence the output.
Output format
| Parameter | Value | Standard |
|---|---|---|
| format | One of: xml, json, jsonv2, geojson, geocodejson | jsonv2 |
| json_callback | Name of the callback function | not set |
The “format” parameter determines the output format.
The “json_callback” parameter is only relevant for JSON output formats. If specified, the JSON output will be wrapped in a callback function with the given name.
Output details
| Parameter | Value | Standard |
|---|---|---|
| Address details | 0 or 1 | 0 |
| Extra tags | 0 or 1 | 0 |
| Name details | 0 or 1 | 0 |
If you want to break down the address into its components, set the “addressdetails” parameter to 1. The exact content of the address breakdown depends on the output format.
If you need additional information in the result that is available in the database, such as a Wikipedia link or opening hours, set “extratags” to 1.
If you are interested in the list of all known names, set “namedetails” to 1. This will also output older names, name variants, references, or brand names.
Output language
| Parameter | Value | Standard |
|---|---|---|
| accept-language | Browser language identifier | Content of the “Accept-Language” HTTP header |
Preferred language order for displaying search results. This can either be a simple comma-separated list of language codes or the same format as the “Accept-Language” HTTP header.
Limit output
| Parameter | Value | Standard |
|---|---|---|
| zoom | 0 – 18 | 18 |
Level of detail required for the address. This is a number roughly corresponding to the zoom level used in XYZ tile sources in frameworks like Maplibre GL. Regarding address details, the zoom levels are as follows:
| zoom | Level of detail⬤ |
|---|---|
| 3 | Country |
| 5 | Federal state |
| 8 | County |
| 10 | City |
| 12 | City / City District |
| 13 | Village / Suburb |
| 14 | Neighborhood |
| 15 | Any settlement |
| 16 | Main roads |
| 17 | Primary and secondary roads |
| 18 | Buildings |
Output of polygons
| Parameter | Value | Standard |
|---|---|---|
| polygon_geojson | 0 or 1 | 0 |
| polygon_kml | 0 or 1 | 0 |
| polygon_svg | 0 or 1 | 0 |
| polygon_text | 0 or 1 | 0 |
Adds the complete geometry of the place to the output of the result. Output formats in GeoJSON, KML, SVG, or WKT are supported. Only one of these options can be used at a time.
| Parameter | Value | Standard |
|---|---|---|
| polygon_threshold | Floating point number | 0.0 |
When one of the polygon_* outputs is selected, a simplified version of the output geometry is returned. The parameter describes the tolerance in degrees by which the geometry may differ from the original geometry. The topology of the geometry is preserved.
Miscellaneous
| Parameter | Value | Standard |
|---|---|---|
| debug | 0 or 1 | 0 |
The “debug” parameter outputs various developer debug information. This includes data about the internals of the “search loop” logic and SQL queries. The output is in HTML format, which overrides the specified machine-readable format.
Address Lookup
The Address Lookup API allows querying the address and other details of one or more OSM objects such as nodes, ways, or relations.
Endpoint
https://api.gdpr-map.eu/lookup?osm_ids=[N|W|R][osm_ids]&[PARAMETER]&key=[API_KEY]The “osm_ids” parameter is mandatory and must contain a comma-separated list of OSM IDs, each marked with its type, either node (N), way (W), or relation (R). Up to 50 IDs can be queried at the same time.
Example
https://api.gdpr-map.eu/lookup?osm_ids=N392410378,W175574445,R56392&key=[API_KEY]Parameter
This section lists additional parameters to further influence the output.
Output format
| Parameter | Value | Standard |
|---|---|---|
| format | One of: xml, json, jsonv2, geojson, geocodejson | jsonv2 |
| json_callback | Name of the callback function | not set |
The “format” parameter determines the output format.
The “json_callback” parameter is only relevant for JSON output formats. If specified, the JSON output will be wrapped in a callback function with the given name.
Output details
| Parameter | Value | Standard |
|---|---|---|
| Address details | 0 or 1 | 0 |
| Extra tags | 0 or 1 | 0 |
| Name details | 0 or 1 | 0 |
If you want to break down the address into its components, set the “addressdetails” parameter to 1. The exact content of the address breakdown depends on the output format.
If you need additional information in the result that is available in the database, such as a Wikipedia link or opening hours, set “extratags” to 1.
If you are interested in the list of all known names, set “namedetails” to 1. This will also output older names, name variants, references, or brand names.
Output language
| Parameter | Value | Standard |
|---|---|---|
| accept-language | Browser language identifier | Content of the “Accept-Language” HTTP header |
Preferred language order for displaying search results. This can either be a simple comma-separated list of language codes or the same format as the “Accept-Language” HTTP header.
Output of polygons
| Parameter | Value | Standard |
|---|---|---|
| polygon_geojson | 0 or 1 | 0 |
| polygon_kml | 0 or 1 | 0 |
| polygon_svg | 0 or 1 | 0 |
| polygon_text | 0 or 1 | 0 |
Adds the complete geometry of the place to the output of the result. Output formats in GeoJSON, KML, SVG, or WKT are supported. Only one of these options can be used at a time.
| Parameter | Value | Standard |
|---|---|---|
| polygon_threshold | Floating point number | 0.0 |
When one of the polygon_* outputs is selected, a simplified version of the output geometry is returned. The parameter describes the tolerance in degrees by which the geometry may differ from the original geometry. The topology of the geometry is preserved.
Miscellaneous
| Parameter | Value | Standard |
|---|---|---|
| debug | 0 or 1 | 0 |
The “debug” parameter outputs various developer debug information. This includes data about the internals of the “search loop” logic and SQL queries. The output is in HTML format, which overrides the specified machine-readable format.
Search & Autocomplete
The “Search & Autocomplete” function provides users with dynamic assistance when entering search queries. Please note that the referrer domain must match the API key as specified in the backend settings.
Endpoint
https://api.gdpr-map.eu/api?q=[SUCHE]&[PARAMETER]&key=[API_KEY]Example
https://api.gdpr-map.eu/api?q=Residenzstraße&key=[API_KEY]Parameter
This section lists additional parameters to further influence the output.
Location-based search
| Parameter | Value | Standard |
|---|---|---|
| lon | Longitude (floating point number) | |
| lat | Latitude (floating point number) | |
| zoom | 1 – 18 | 16 |
| location_bias_scale | 0.0 – 1.0 | 0.2 |
There are two optional parameters to influence the location-based search. ‘zoom’ describes the radius around the center to focus on. This is a number that should roughly correspond to the zoom parameter of a respective map display.
The parameter location_bias_scale describes how strongly the relevance of a result should be considered. Reasonable values range from 0.0 (relevance is almost entirely ignored) to 1.0 (relevance is given approximately equal weight).
Example
https://api.gdpr-map.eu/api?q=berlin&lon=10&lat=52&zoom=13&location_bias_scale=0.2&key=[API_KEY]Adjust language and number of results
| Parameter | Value |
|---|---|
| long | ISO 639-1 Code |
| limit | Integer |
Der Parameter “lang” definiert die Sprache der Suchergebnisse, wobei die Sprachcodes gemäß ISO 639-1, wie beispielsweise “de” für Deutsch oder “en” für Englisch, verwendet werden sollten.
The “limit” parameter allows the number of displayed search results to be restricted.
Example
https://api.gdpr-map.eu/api?q=Residenzstraße&limit=2&lang=de&key=[API_KEY]Filter
The filter function allows for more precise restriction of search results by applying filters such as a bounding box, OSM tags, and layers. These tools provide refined control over the displayed data by limiting the results to specific geographic areas and certain attributes.
Bounding Box
| Parameter | Value |
|---|---|
| bbox | [minLon,minLat,maxLon,maxLat] (Floating point numbers) |
Filtering by a bounding box allows for targeted searches within a defined geographic area. The coordinates of this box are specified in the format [minLon, minLat, maxLon, maxLat], where ‘minLon’ and ‘minLat’ define the minimum longitudes and latitudes, and ‘maxLon’ and ‘maxLat’ define the maximum longitudes and latitudes. These values thus determine the corners of the rectangular search area on the map.
Example
https://api.gdpr-map.eu/api?q=Berlin&bbox=9.5,51.5,11.5,53.5&key=[API_KEY]OSM Tag
| Parameter | Value |
|---|---|
| osm_tag | [key:value] |
This filter works only for main OSM tags, and not all OSM tag/value combinations can be searched. All tag/value combinations with a ‘main’ property are included in the database. If one or more query parameters are present, the results will be filtered by these tags. Use the following syntax:
| Description | Parameter |
|---|---|
| Include places with the tag | osm_tag=key:value |
| Exclude places with the tag | osm_tag=!key:value |
| Include places with the tag key | osm_tag=key |
| Include places with the tag value | osm_tag=:value |
| Orte mit Tag-Schlüssel ausschließen | osm_tag=!key |
| Exclude places with the tag value | osm_tag=:!value |
Eine Auflistung aller OSM-Tags finden Sie hier.
Examples
Search for all places named München with the tag tourism=museum search:
https://api.gdpr-map.eu/api?q=München&osm_tag=tourism:museum&key=[API_KEY]Search only by the key tourism:
https://api.gdpr-map.eu/api?q=München&osm_tag=tourism&key=[API_KEY]Layer
You also have the option to filter by layers. The following layers are available:
| Value | Description |
|---|---|
| house | Buildings |
| street | street |
| locality | Locality |
| district | District |
| city | City |
| county | County |
| state | Federal state |
| country | Country |
Example
https://api.gdpr-map.eu/api?q=München&layer=city&layer=locality&key=[API_KEY]Static maps
Static maps are PNG images generated by an API, created from map data. This API allows the creation of fixed, unchangeable map views, ideal for presentation purposes. Access to the API is restricted and requires whitelisting of the user’s IP address in the dashboard.
Endpoint
https://maps02.gdpr-map.eu/static/map.php?[PARAMETER]&key=[API_KEY]Parameter
This section lists additional parameters to further influence the output.
Creation of static map images
| Parameter | Value |
|---|---|
| style | one of: basic, dark-matter, osm-bright, positron |
| width | Integer [500;5000] |
| height | Integer [500;5000] |
| zoom | Integer [3;22] |
| clat | Floating point number |
| clng | Floating point number |
| marker | bool [0;1] |
- style (String, required): Determines the style of the map. Possible options are ‘basic’, ‘dark-matter’, ‘osm-bright’, and ‘positron’.
- width (Integer, required): The width of the generated image in pixels. The value must be between 500 and 5000.
- height (Integer, required): The height of the generated image in pixels. The value must also be between 500 and 5000.
- zoom (Integer, required): The zoom level of the map, which determines the level of detail. Acceptable values range from 3 to 22.
- clat (Float, required): The geographical latitude of the center of the map.
- clng (Float, required): The geographical longitude of the center of the map.
- marker (Boolean, optional): Determines whether a marker is placed at the center of the map. Possible values are 0 (no marker) and 1 (place marker), with the default value being 0.
Example
http://map02.gdpr-map.eu/static/map.php?style=basic&width=1000&height=1000&zoom=13&
clng=48.13715069724989&clat=11.575440849258712&marker=1&key=[API_KEY]