IMPORTANT NOTICE: The Mapcode Foundation provides an implementation of the Mapcode REST API at:

                  This free online service is provided for demonstration purposes only and the Mapcode
                  Foundation accepts no claims on its availability or reliability, although we'll try hard
                  to provide a stable and decent service. Note that usage or log data may be collected, only
                  to further improve service (never for commercial purposes). If you are interested in using
                  the service for professional purposes, or in high-availability or high-demands contexts,
                  you may wish to consider self-hosting this service. The source code is open-source and
                  available at:

The REST API Methods

All REST services (except 'metrics') are able to return both JSON and XML. Use the HTTP
'Accept:' header to specify the expected format: application/json or application/xml
If the 'Accept:' header is omitted, JSON is assumed.

GET /mapcode         Returns this help page.
GET /mapcode/version Returns the software version.
GET /mapcode/metrics Returns some system metrics (JSON-only, also available from JMX).
GET /mapcode/status  Returns 200 if the service OK.

GET /mapcode/codes/{lat},{lon}[/[mapcodes|local|international]]
     [?precision=[0..8] & territory={restrictToTerritory} & country={restrictToCountry}
     alphabet={alphabet} & include={offset|territory|alphabet|rectangle}]

   Convert latitude/longitude to one or more mapcodes. The response always contains the 'international' mapcode and
   only contains a 'local' mapcode if there are any non-international mapcode AND they are all of the same territory.

   The 'country' parameter always specifies a country, by a 2 or 3 character ISO-3166 code, like 'US' or 'USA'
   (for the USA), and 'NL' or 'NLD' (for the Netherlands). In a web environment, the country code is often available
   as a 2-character code. That code can be used for this parameter.

   The 'territory' parameter is a 2, 3 or 5 (XX-YY) character code. These code can be countries or states within countries.
   Some 2 character state codes are the same as country codes. In that case, the territory implies the state, not the country.
   For example, the territory code 'US' is unambiguous and means USA, but 'NL' means 'IN-NL' (Nagaland, India) rather than
   the Netherlands. You cannot use the standard 2-character country codes in web applications for this parameter.

   Path parameters:
     lat             : Latitude, range [-90, 90] (automatically limited to this range).
     lon             : Longitude, range [-180, 180] (automatically wrapped to this range).

   An additional filter can be specified to limit the results:
     mapcodes        : Same as without specifying a filter, returns all mapcodes.
     local           : Return the shortest local mapcode (not an international code). Note that multiple local
                       mapcodes may exist for a location, with different territories. This method returns the
                       shortest code. It does not check if the territory is the 'geographically correct' one
                       for the coordinates. To get the shortest code for a specific territory, you need to explicitly
                       specify the territory with 'territory=' parameter in the query.
     international   : Return the international mapcode.

   Query parameters:
     precision       : Precision, range [0..8] (default=0).
     territory       : Territory (country or state) to restrict results to (name or alphacode).
     country         : Country to restrict results to (name or alphacode).
     alphabet        : Alphabet to return results in.
     include         : Multiple options may be set, separated by comma's:
                         offset    = Include offset from mapcode center to lat/lon (in meters).
                         territory = Always include territory in result, also for territory 'AAA'.
                         alphabet  = Always the mapcodeInAlphabet, also if same as mapcode.
                         rectangle = Include the encompassing rectangle of a mapcode.

                       Note that you can use 'include=territory,alphabet' to ensure the territory code
                       is always present, as well as the translated territory and mapcode codes.
                       This can make processing the records easier in scripts, for example.

GET /mapcode/coords/{code} [?context={territory} & include={include}]
   Convert a mapcode into a latitude/longitude pair.

   Path parameters:
     code            : Mapcode code (local or international). You can specify the territory in the code itself,
                       like 'NLD%20XX.XX' (note that the space is URL-encoded to '%20'), or you specifty the
                       territory separately in the 'context=' parameter, like 'XX.XX?context-NLD'.
   Query parameters:
     context         : Optional mapcode territory context (name or alphacode). The context is only used if the

                       code is ambiguous without it, otherwise it is ignored. For example, the context is ignored
                       when converting an international code (but it is not considered an error to provide it).
     include         : An additional option may be set:
                         rectangle = Include the encompassing rectangle of a mapcode.

GET /mapcode/territories [?offset={offset}&count={count}]
   Return a list of all territories.

GET /mapcode/territories/{territory} [?context={territory}]
   Return information for a single territory code.

   Path parameters:
     territory       : Territory to get info for (name or alphacode).

   Query parameters:
     context         : Territory context (optional, for disambiguation, name or alphacode).
                       The context can only be: USA IND CAN AUS MEX BRA RUS CHN ATA

GET /mapcode/alphabets [?offset={offset}&count={count}]
   Return a list of all alphabet codes.

GET /mapcode/alphabets/{alphabet}
   Return information for a specific alphabet.

   Path parameters:
     alphabet        : Alphabet to get info for.

General query parameters for methods which return a list of results:

   offset            : Return list from 'offset' (negative value start counting from end).
   count             : Return 'count' items at most.

JSON and XML Responses

The REST API methods defined above obey the HTTP "Accept:" header. To retrieve JSON responses,
use "Accept:application/json", to retrieve XML responses, use "Accept:application/xml".

The default response type is JSON, if no "Accept:" header is specified.

Note that some browsers (such as FireFox) may silently insert an 'Accept:' header when using a
XMLHttpRequest in Javascript. This may lead to returning JSON in some browsers and XML in others.
It is advised to explicitly set the appropriate header in Javascript in such cases.

Alternatively, to retrieve XML or JSON responses if no "Accept:" header is specified, you can add
"/xml" or "/json" in the URL, directly after "/mapcode".

So, the following methods are supported as well and return XML or JSON by default:

    GET /mapcode/xml/version           GET /mapcode/json/version
    GET /mapcode/xml/status            GET /mapcode/json/status
    GET /mapcode/xml/codes             GET /mapcode/json/codes
    GET /mapcode/xml/coords            GET /mapcode/json/coords
    GET /mapcode/xml/territories       GET /mapcode/json/territories
    GET /mapcode/xml/alphabets         GET /mapcode/json/alphabets