Location search API - third generation

The meteoblue location search API resolves location names, postal codes, icao and iata codes to standardised WGS84 latitude and longitude coordinates that can be used with the meteoblue API. For a quick demonstration try our website, which also uses the API as well. Features:

Features

• Search world-wide: "New York" or "Basel"
• Postal codes : "4058" for Basel-City
• ICAO and IATA airport codes: "LFSB" or "BSL" for EuroAirport Basel–Mulhouse
• Fuzzy matching: "Berl" returns "Berlin"
• Surrounding locations: "47.56°N 7.57°E" lists locations around Basel
• Location awareness: "Ber" finds "Bern" for users around Bern and "Berlin" for users around Berlin
• Intelligent results ranking: Based on location importance, population and location awareness
• Localised results: "Bâle" is shown in French for "Basel"
• Special character matching: German umlauts, Cyrillic and Arabic characters are transformed to Latin
• Solid foundation: Based on most-recent GeoNames database
• Performance: Responds within 0.1 seconds; ideal for AJAX applications
• JSON + HTTPS

The meteoblue location search API is available for non-commercial use free of charge. For commercial use a usage agreement is required. Please contact us for further information.

Getting started

Retrieve location information

To query the location search API, simply send an HTTPS request. Let's search for Basel: https://www.meteoblue.com/en/server/search/query3?query=basel. The response should look similar to:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

    "query": "basel",
    "currentPage": 1,
    "itemsPerPage": 10,
    "pages": 5,
    "count": 42,
    "orderBy": "ranker DESC",
    "type": "name",
    "results": [
    {
    "name": "Basel",
    "iso2": "CH",
    "country": "Switzerland",
    "admin1": "Canton of Basel-Stadt",
    "lat": 47.558399,
    "lon": 7.57327,
    "asl": 279,
    "timezone": "Europe/Zurich",
    "population": 164488,
    "icao": "",
    "iata": "EAP",
    "postcodes": ["4000","4001","4031","..."],
    "url": "basel_switzerland_2661604"
    },
    {...}]
    

In this example "Basel" matches 42 entries ("count": 42). 10 entries are shown on each page ("itemsPerPage": 10 limit). There are 4 pages with 10 entries and the last page with 2 entries, so the matches are shown on 5 pages in total. Each result item contains detailed information about a location, most notably its localised name, country, elevation in meters above sea level ("asl") and coordinates ("lat" and "lon").

Every query consists of two parts: query string "/en/server/search/query3" and parameters "?query=basel". The query string can be modified to show results for a different locale (e.g. "/fr/" for french). "query3" indicates our third generation search API. Query parameter can be varied as specified below.

Example queries

The following example queries explain most features. You are also welcome to use the location-search API implementation on our website. We use JavaScript with AJAX and query this API for each keystroke.

Tip: The API returns only JSON formatted results. Some browser extensions format JSON in human readable way. For Example JSONView for Firefox for Chrome. Otherwise the output is a bit complicated to read.

• ?query=basel: Search for Basel and display the results in German.
• ?query=70173&iso2=de: Postal code 70173 in Germany. "Stuttgart" in "Baden-Württemberg" is shown.
• ?query= (empty query) Locations around user position (geo ip resolution).
• ?query=47.5761%207.5999 List locations around 47.57°N / 7.6°E ("%20" represents an url encoded white space).
• ?query=Berlin&orderBy=asl%20DESC Search for the highest Berlin at 3756m above sea level (asl) in Bolivia.
• ?query=Zurich&itemsPerPage=1 Find the first location matching Zurich.
• ?query=40%C2%B0%202... Search locations around 40° 26′ 45.6″ N 79° 58′ 55.2″ W.
• ?query=40%C2%B0%202...%20Bald Look for "Bald" at given coordinates. Now Baldwin is found as first entry.
• ?query=New%20York&page=2&itemsPerPage=5 Show results 6-10 for New York.
• ?query=%D0%9C... Search for "Москва" (Moscow) in Russian.
• ?query=Paris&callback=myCallbackFunction Query for "Paris" with JSONP callback function.

Input parameter

Search queries support place names, postcodes, coordinates, iata and ICAO codes. The search algorithm automatically detects the type of the query and will return corresponding data. All input is fuzzy matched and allows typos to a certain degree. Special character like umlauts and most common coordinate-formats are detected and transformed.

Sorting and pagination

The sorting algorithms have been trained for 2 years to achieve high usability and performance. Per default results are ordered by a ranker based on match-relevance, language, importance of a location (e.g. capital), population and distance to the current user. The results are highly depended on the users language and location. For short (1-2 character) queries the API will not return practical results as short character sequences match hundreds of thousands locations. We recommend at least 3 character queries for useful results.

The location search API returns for most queries more than 100 results. We recommend using pagination and display only 10-20 results at once. The API will never display or return more than 1000 results. The following GET parameter control basic ordering and pagination:

Output - Search function information

The returned JSON structure contains the following keys:

Output - Location information

Each location item in the "results" array contains:

Examples

JSON with jQuery

The easiest way to retrieve location data in JavaScript is with jQuery and a JSON-formatted result.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

            var params = {
            query: "Hamburg", // set parameter "query"
            iso2: "DE", // set parameter "iso2"
            };

            $.ajax({
            url: "https://www.meteoblue.com/en/server/search/query3",
            data: params // add parameter to ajax request
            }).done(function(data) { printAllNames(data); });

            function printAllNames(data) {
            var results = data.results;
            for(var i in results) {
            if(results.hasOwnProperty(i)) {
            console.log(results[i]["name"]);
            }
            }
            }
            

This simple example will print the exact names of 10 locations that match the search term "Hamburg" in Germany ("iso2=DE") on the console.

Bypassing the JavaScript same-origin policy

We properly set all origin-policy headers. Older browsers do not allow a page to receive data from a different origin. With JSONP, this restriction is bypassed by wrapping a function call around the JSON data in the response. The example above only needs slight adjustments to work with JSONP.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

                    var params = {
                    query: "Tokyo",
                    iso2: "JP"
                    };
                    $.ajax({
                    cache: true, // enable caching of the results
                    dataType: "jsonp", // enable JSONP
                    jsonpCallback: "printAllNames", // use "printAllNames" as callback
                    url: "https://www.meteoblue.com/en/server/search/query3",
                    data: params // add parameters to ajax request
                    });

                    function printAllNames(data) {
                    var results = data.results;
                    for(var i in results) {
                    if(results.hasOwnProperty(i)) {
                    console.log(results[i]["name"]);
                    }
                    }
                    }
                    

As expected, the names of the first 10 locations that match the search Term "Tokyo“ will be printed in console. The "done" function, that was used before to pass the data to the "printAllNames" function is not required anymore, as it will be called directly from the response to the AJAX request.

PHP with cURL

This example shows how to use cURL in PHP with our location search API. The function "getLocationCoords" returns the latitude, longitude and elevation of the first match. Those three parameters should be used when requesting weather data from the meteoblue API.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

                            private function getLocationCoords($query = "Basel", $iso2 = "CH") {
                            $parameters = array("query" => $query, "iso2" => $iso2);
                            $url = "https://www.meteoblue.com/en/server/search/query3?";
                            $url .= http_build_query($parameters);
                            $ch = curl_init($url);
                            curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
                            $json = curl_exec($ch);
                            $data = json_decode($json);
                            $coords = array();
                            $coords["lat"] = (float)$data->results["0"]->lat;
                            $coords["lon"] = (float)$data->results["0"]->lon;
                            $coords["asl"] = (int)$data->results["0"]->asl;
                            /*
                            * print_r($coords):
                            * Array
                            * (
                            * [lat] => 47.5582
                            * [lon] => 7.5881
                            * [asl] => 260
                            * )
                            */
                            return $coords;
                            }
                            

Appendix

Feature classification

Feature codes