Battuta!

World={"Country", "Region", "City"};


A location API provider, by medunes

GET/ {API_KEY}



Show case

See the full code on Codepen

Usage

New! Quota monitoring

  • You can monitor the remaining quota of requests per key through the following query:
  • This request of course will not decrease your quota
    • url="http://battuta.medunes.net/api/quota/?key={YOUR_API_KEY}

General info

API Key

  • A 32 byte long hash key
  • It must be provided in every request
  • If the key is absent the following response will be sent back 
    {"error":"Missing API key. Please visit battuta.medunes.net to get an API key. Also read the documentation for more information."}
  • If the key is wrong the following response will be sent back 
    {"message":"Authentication credentials could not be found."}
  • The max number of API requests is 500 requests. This is due to server performance and to prevent malicious behaviours. If you need a higher quota, please contact us at battuta@medunes.net

Requests & parameters

  • All API requests must be in HTTP GET method
  • Some requests do not accept any parameters. Others do accept precise numbers and couplings of parameters. It all depends on the specifications (see details below). When you send an unallowed parameter, a HTTP_BAD_REQUEST header with a JSON error message body will be sent back to you. Here is an example of an erronous request and its response: 
    url="http://battuta.medunes.net/api/country/all/?key={API_KEY}&wrongParam=value"
    {"error":"Unknown parameters: wrongParam. PLease check the API documentation for more details."}

Specifications

  • Battuta API has been built to provide data about locations in the world.
  • It letS you seek data with a country-oriented search, region-oriented search and city-oriented search.
  • Sometimes, you might consider that two or more requests are interchangeables or duplicates. Indeed, even if the result is the same, we allow different ways of describing the query.
    1- Country

    List all countries

    Request 
    url="http://battuta.medunes.net/api/country/all/?key={YOUR_API_KEY}"
    Response 
    [{"name":"COUNTRY_NAME_1","code":"COUNTRY_CODE_1"},{"name":"COUNTRY_NAME_2","code":"COUNTRY_CODE_2"},..]
    Description
    • Lists all countries of the world
    • The members of the reponse JSON object are as follows:
      1. code: The ISO 3166-1 alpha-2 standard country code (ex:TN/US/JP/DE)
      2. name: the full name of the country (ex: Tunisia, Japan, Germany)
    Rules
    • No parameters are allowed for this request.

    Country by code

    Request 
    url="http://battuta.medunes.net/api/country/code/kr/?key={YOUR_API_KEY}"
    Response 
    [{"name":"Korea (South)","code":"kr"}]
    Description
    • Returns a single JSON object containing the name and the code of the country requested by its alpha-2 country code
    • The members of the JSON object are as follows:
      1. code: The ISO 3166-1 alpha-2 standard country code (ex:TN/US/JP/DE)
      2. name: the full name of the country (ex: Tunisia, Japan, Germany)
    Rules
    • No parameters are allowed for this request.

    • If the requested country code doesn't exist, an empty array JSONwill be returned. Ex:

      Request 
      url="http://battuta.medunes.net/api/country/code/pq/?key={YOUR_API_KEY}"
      Response 
      []

    Country by name, region or city

    Request 
    url="http://battuta.medunes.net/api/country/search/?country={COUNTRY_NAME_HINT}& region={REGION_NAME_HINT}&city={CITY_NAME_HINT}&key={YOUR_API_KEY}"
    Response 
    [{"name":"COUNTRY_NAME_1","code":"COUNTRY_CODE_1"},{"name":"COUNTRY_NAME_2","code":"COUNTRY_CODE_2"},..]
    Description
    • Lists all countries which names, regions and cities contain hints(parts of text) given in the request URL.
    Rules
    • The allowed request parameter names are:
      1. country: text which should figure in the name of the searched country
      2. region: text which should figure in the name of any region belonging to the searched country
      3. city: text which should figure in the name of any city belonging to the searched country
    • The list of parameters can go from 0 to 3:
      1. No parameters:(lists all countries of the world)
      2. One parameter:country or region or city
      3. Two parameters: country and region or country and city or region and city
      4. Three parameters: country and region and city

    • If no requested countries with the given parameters do exist, an empty JSON arraywill be returned. Ex:

      Request 
      url="http://battuta.medunes.net/api/country/search/?region=zzz&key={YOUR_API_KEY}"
      Response 
      []
    2- Region

    Important:

  • Unlike country-oriented search where you can narrow your query using three parameters: country-region-city, region oriented searches must be relative to a unique country represented by its alpha-2 code. This choice has been made mainly for the safety and performance of the server and prevent eventual exhaution.

    • List all regions

    Request 
    url="http://battuta.medunes.net/api/region/{COUNTRY_CODE}/all/?key={YOUR_API_KEY}"
    Response 
    [{"region":"REGION_NAME_1","code":"COUNTRY_CODE",{"region":"REGION_NAME_2","code":"COUNTRY_CODE",..]
    Description
    • Lists all regions of a single country given its alpha-2 code
    • The members of the reponse JSON object are as follows:
      1. country: The ISO 3166-1 alpha-2 standard country code (ex:TN/US/JP/DE)
      2. region: the full name of the region (ex: Sousse, California,Tokyo,Berlin)
    Rules
    • No parameters are allowed for this request.

    Region by name or city

    Request 
    url="http://battuta.medunes.net/api/country/search/?region={REGION_NAME_HINT}&city={CITY_NAME_HINT}&key={YOUR_API_KEY}"
    Response 
    [{"name":"REGION_NAME_1","code":"COUNTRY_CODE"},{"name":"REGION_NAME_2","code":"COUNTRY_CODE"},..]
    Description
    • Lists all regions which names and cities contain hints(parts of text) given in the request URL.
    Rules
    • The allowed request parameter names are:
      1. region: text which should figure in the name of the searched region
      2. city: text which should figure in the name of any city belonging to the searched region
    • The list of parameters can go from 0 to 2:
      1. No parameters:(lists all regions of the country given its alpha-2 code)
      2. One parameter:region or city
      3. Two parameters:region and city

    • If no requested regions with the given parameters do exist, an empty JSON arraywill be returned. Ex:

      Request 
      url="http://battuta.medunes.net/api/dz/region/search/?region=ontario&key={YOUR_API_KEY}"
      Response 
      []
    3- City

    Important:

  • Unlike country-oriented search where you can narrow your query using three parameters: country-region-city, city oriented searches must be relative to a unique country represented by its alpha-2 code. Also, listing all cities of a country is not available, a parameter based query is rather offered where you must provide at least a city hint or a region hint as described below.
  • Unlike country-oriented search and region-oriented search where you can narrow your query using hints of any text lengths, in city based searches,hints must be at least 3 characters length , else, a HTTP_BAD_REQUEST header and JSON error body will be sent back to you. Here is an example:
    • Request 
    url="http://battuta.medunes.net/api/city/fr/search/?region=pa&key={YOUR_API_KEY}"
    Response 
    {"error":"The region parameter must be at least three (3) characters long. Check documentation for more details."}
  • This choice has been made mainly for the safety and performance of the server and to prevent eventual exhaution.

    • City by name or region

    Request 
    url="http://battuta.medunes.net/api/city/search/?region={REGION_NAME_HINT}&city={CITY_NAME_HINT}&key={YOUR_API_KEY}"
    Response 
    [{"city":"CITY_NAME_1","region":"REGION_NAME_1","country":"COUNTRY_CODE","latitude":"CITY_LATITUDE_1","longitude":"CITY_LONGITUDE_1"},{"city":"CITY_NAME_2","region":"REGION_NAME_2","country":"COUNTRY_CODE","latitude":"CITY_LATITUDE_2","longitude":"CITY_LONGITUDE_2"},..]
    Description
    • Lists all cities which names and regions contain hints(parts of text) given in the request URL.
    Rules
    • The allowed request parameter names are:
      1. city: text which should figure in the name of the searched city
      2. region: text which should figure in any region to which the searched cities belong
    • The list of parameters can go from 1 to 2:
      1. One parameter:region or city
      2. Two parameters:region and city

    • If no requested cities with the given parameters do exist, an empty JSON arraywill be returned. Ex:

      Request 
      url="http://battuta.medunes.net/api/city/jp/search/?city=paris&key={YOUR_API_KEY}"
      Response 
      []

    AJAX Requests

    • Due to some CORSrestrictions, you might be unable to correctly receive data using AJAX calls. to overcome this, we provide JSONP API service
    • The url for the JSONP call must use the callback parameter
    • Here is an example url using JSONP 
      url="http://battuta.medunes.net/api/city/jp/search/?city=paris&callback=?&key={YOUR_API_KEY}

Contact



To report bugs, send suggestions, support and all kinds of contacts please send emails to: contact@medunes.net