Skip to main content

Location Search API

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 Package API. For a quick demonstration try our website, which 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 requires a valid API key (as well as a signature, if the API key is protected with a shared secret). It is available for non-commercial use free of charge. For commercial use a usage agreement is required. Please contact us for further information and an API key.

Retrieve Location Information​

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

"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 call consists of two parts: call string "/en/server/search/query3" and parameters "?query=basel". The call string can be modified to show results for a different locale (e.g. "/fr/" for french). "query3" indicates our third generation search API. Call parameter can be varied as specified below.

Example Calls​

The following example calls explain most features. You are also welcome to use the Location Search API implementation on our website. We use JavaScript with AJAX and call 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.

Input Parameter​

Search calls support place names, postcodes, coordinates, iata and ICAO codes. The search algorithm automatically detects the type of the call 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.

ParameterTypeDescription
querystringRequired. The search term. Attention: Special character should be url encoded
language2 characterRequired. Language is defined in the URL prefix: https://www.meteoblue.com/de/... for results in german
iso22 characterThe country is specified by its ISO2 code. "DE" for Germany
callbackstringEnables JSONP output with the specified callback function to bypass JavaScript same origin policy for older browsers
apikeystringRequired to call the Location Search API

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) calls the API will not return practical results as short character sequences match hundreds of thousands locations. We recommend at least 3 character calls for useful results.

The Location Search API returns for most calls 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:

ParameterTypeDescription
orderBystringDefault is "ranker DESC". The results can be sorted by every parameter of the location output. Append "ASC" for ascending or "DESC" for descending order, e.g. "asl DESC" to list the highest locations first.
pagenumberDefault is 1 (first page).
itemsPerPagenumberDefault is 10. Specifies the number of items that are included in the response. Use the page parameter to get more results. Maximum is 100.

Output​

Search Function Information​

The returned JSON structure contains the following keys:

ParameterTypeDescription
typestringDetected call type. "Name" or "Coord"
iso22 characterISO2 country code.
queryutf-8 stringThe search term.
orderBystringThe column that has been used to sort the results, and "ASC" or "DESC" for ascending or descending order.
latnumberCoordinate search only. The latitude value of the call.
lonnumberCoordinate search only. The longitude value of the call.
radiusnumberOnly relevant with coordinate search. The radius around the given coordinates that was used to search for locations in kilometers
countnumberTotal number of results
pagesnumberTotal number of results
itemsPerPagenumberMaximum amount of results per page.
currentPagenumberNumber of the current page.

Location Information​

Each location item in the "results" array contains:

ParameterTypeDescription
nameuft-8 stringhe full localised name of the location, with special characters like ä or è.
iso22 characterCountry iso2 code
countryuft-8 stringLocalised country name
admin1uft-8 stringLocalised name of the first administrative area.
latnumberThe latitude of the location in decimal notation.
lonnumberThe longitude of the location in decimal notation.
timezonestringThe timezone of the location.
populationnumberPopulation
distancenumberDistance for coordinate search or geo-ip reference point
icaostringICAO code
iatastringIATA code
postcodesstring arrayList of postcode for each location
featureClassstring arrayFeature class (see appendix)
featureCodestringFeature code
urlstringmeteoblue URL syntax used for links on our website

Examples​

JSON with jQuery​

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

var params = {
  query: "Hamburg", // set parameter "query"
  iso2: "DE", // set parameter "iso2"
  apikey: "DEMOKEY", // set API-key
  sig: "siuhaefiusf" // only required if the API-key is protected with a signature
};

$.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.

var params = {
  query: "Tokyo",
  iso2: "JP",
  apikey: "DEMOKEY",
  sig: "siuhaefiusf"
};

$.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 call.

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 calling weather data from the meteoblue API.

private function getLocationCoords($query = "Basel", $iso2 = "CH", $apikey = "DEMOKEY", $sig = "siuhaefiusf") {
    $parameters = array("query" => $query, "iso2" => $iso2, "apikey" => $apikey, "sig" => $sig);
    $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​

featureClassDescription
AAdministrative Boundary Features
HHydrographic Features
LArea Features
PPopulated Place Features
SSpot Features
THypsographic Features

Feature Codes​

featureCodeDescription
ADM1first-order administrative division
ADM2second-order administrative division
ADM3third-order administrative division
ADM4fourth-order administrative division
ADM5fifth-order administrative division
PCLIindependent political entity
PCLDdependent political entity
PCLIXsection of independent political entity
PCLSsemi-independent political entity
TERRterritory
PCLFfreely associated state
PCLpolitical entity
PPLpopulated place
PPLLpopulated locality
PPLCcapital of a political entity
PPLAseat of a first-order administrative division
PPLA2seat of a second-order administrative division
PPLA3seat of a third-order administrative division
PPLA4seat of a fourth-order administrative division
PPLXsection of populated place
PPLSpopulated places
PPLCHhistorical capital of a political entity
AMUSamusement park
AIRPairport
MTmountain
MTSmountains
PKpeaks
PANpan
PANSpans
PASSpass
VALLvalley
FLLwaterfall(s)
DAMdam
PRKpark
GLCRglacier(s)
contcontinent
RSVreservoir(s)
UPLDupland
ISLisland
ISLETislet
ISLFartificial island
ISLMmangrove island
ISLSislands
ISLTland-tied island
CAPEcape
HUThut
HUTShuts
RSRTresort
CMPcamp(s)
CMPMNmining camp
CLFcliff(s)
Last updated on