C library to convert between mapcodes and latitude/longitude

Version 1.40

Copyright ©2003-2014 by The Mapcode Foundation

1. Converting a coordinate into a mapcode

int encodeLatLonToMapcodes(

char** results,

double lat,

double lon,

int territoryCode,

int extraDigits)

find all possible mapcodes in a given territory (or in ALL territories)

input:

• lat: latitude in degrees -90.0 to 90.0
• lon: longitude in degrees -180.0 to 180.0
• territoryCode: territory code (an integer, pass 0 to encode in ALL possible territories, or a positive value to encode only in a particular territory)
• extraDigits: number of extra "digits" to add to the generated mapcode. The preferred default is 0. Other valid values are 1 and 2. see section 2.2 below.

output:

• return value: the number of results
• results: elements are made to point to strings (2 strings per result!) representing the mapcodes of the given latitude/longitude in the specified territory. Note that these pointers are overwritten by the next call to encodeLatLonToMapcodes.
• Of each pair of strings, the first string specifies the official printable territory abbreviation (e.g. “NLD” for The Netherlands, “US-CA” for the state of California in the United States of America)
• The second string is a mapcode (a string between 5 and 10 chars with a dot in it)

int encodeLatLonToSingleMapcode(

char* result,

double lat,

double lon,

int territoryCode,

int extraDigits)

find ONE possible mapcode in a given territory (or in ALL territories)

input:

• lat: latitude in degrees -90.0 to 90.0
• lon: longitude in degrees -180.0 to 180.0
• territoryCode: territory code (an integer, pass 0 to encode in ALL possible territories, or a positive value to encode only in a particular territory)
• extraDigits: number of extra "digits" to add to the generated mapcode. The preferred default is 0. Other valid values are 1 and 2. see section 2.2 below.

output:

• return value: positive if a mapcode was found
• result: a string representing the full mapcode found, including territory code; the caller must allocate the memory for the result string (contrary to encodeLatLonToMapcodes!); make sure there is room for the worst-case result (which is a string of char[24]).

Example code:

double lat = 52.376514;

double lon = 4.908542;

const char* countryabbr = "NLD";

char* r[MAX_NR_OF_MAPCODE RESULTS]; // Strings allocated by library!

int tc = convertTerritoryNameToCode(countryabbr, 0);

int nrresults = encodeLatLonToMapcodes(r, lat, lon, tc, 0);

if (nrresults > 0)

printf("%0.6f,%0.6f has mapcode %s %s\n", lat, lon, r[1], r[0]);

else

printf("No results\n");

Output:

52.376514,4.908542 has mapcode NLD 49.4V

Thus, convertTerritoryNameToCode is used to determine the territory code tc for “NLD”. Then encodeLatLonToMapcodes is used to determine the mapcode for the coordinate 52.376514,4.908542. The first one of those (if any) is printed.

Note that there may be more than one result, even for a single territory.

When you only want ONE result, you could also write:

double lat = 52.376514;

double lon = 4.908542;

const char* countryabbr = "NLD";

char result[MAX_MAPCODE_RESULT_LEN]; // String allocated by caller!

int tc = convertTerritoryNameToCode(countryabbr, 0);

int nrresults = encodeLatLonToSingleMapcode(result, lat, lon, tc, 0);

if (nrresults > 0)

printf("%0.6f,%0.6f has mapcode %s\n", lat, lon, result);

else

printf("No results\n");

You can also generate all possible mapcodes, irrespective of territory, by passing territoryCode=0:

int i;

double lat = 52.376514;

double lon = 4.908542;

char *r[MAX_NR_OF_MAPCODE_RESULTS];

int nrresults = encodeLatLonToMapcodes(r, lat, lon, 0, 0);

printf("%d mapcodes for %0.6f,%0.6f:\n", nrresults, lat, lon);

for (i = 0; i < nrresults; i++) {

// show context (unless it is international)

if (strcmp(r[(i * 2) +1], "AAA") !=0 )

printf("%s ",r[(i * 2) + 1]);

// show mapcode

printf("%s\n", r[i * 2] );

}

Output:

5 possible mapcodes for 52.376514,4.908542:

NLD 49.4V

NLD G9.VWG

NLD DL6.H9L

NLD P25Z.N3Z

VHXGB.1J9J

Note that encodeLatLonToMapcodes(r, lat, lon, 0, e) is guaranteed to return at least one result if lat, lon is in range (i.e. on Earth). Again, the elements of r are made to point to territory abbrevations and mapcodes in those territories. Within territories the shortest mapcode code is listed first. The territories are listed in no particular order, except that the international code is always the last code in the list.

2. Converting a mapcode into a coordinate

int decodeMapcodeToLatLon(

double* lat,

double* lon,

const char* mapcode,

int territoryCode)

input:

• mapcode: a “free-form” user input, which may be recognized if it is of the form
• [xxx[-yyy]] PPP.QQQ [-RR]
• xxx is a country code (2 or 3 characters)
• yyy is an state code (2 or 3 characters)
• PPP : mapcode prefix (between 2 and 5 characters)
• QQQ: mapcode postfix (between 2 and 4 characters)
• RR: high-precision addendum (one or two characters)
• territoryCode: territory (or 0), to help disambiguate the user input if that proves necessary; If you pass 0, the mapcode may fail to decode, or (if it is ambiguous) will be disambiguated randomly.
• Examples:
• user input “US-CA XX.XX” needs no disambiguation and returns a location in California
• user input “IN XX.XX” can be decoded without a tc, but it is unpredictable whether it decodes to a location in Indiana, USA or in the Ingushetia, Russia.
• user input “XX.XX” is impossible to decode unless a valid tc is provided

output:

• returns nonzero in case of error. Otherwise, lat and lon are filled with the decoded coordinates.

Example code:

const char* userinput = "NLD 49.4V";

double lat, lon;

int err = decodeMapcodeToLatLon(&lat, &lon, userinput, 0);

if (err)

printf("\"%s\" is not a valid mapcode\n", userinput);

else

printf("\"%s\" represents %0.6f,%0.6f\n", userinput, lat, lon);

Output:

"NLD 49.4V" represents 52.376514,4.908542

Note that the above piece of code will only “accidentally” handle ambiguous partial mapcodes correctly. For example,

userinput=”IN VY.HV”

will either be interpreted as an abbreviation of “US-IN VY.HV” or of “RU-IN VY.HV”, and thus either produce a coordinate in Indiana, USA, or in Ingushetia, Russia.

Passing a “default context” improves the chances of ambiguous user input to be interpreted “as the user intended”. Thus, if one builds a system that is mostly going to be used in the USA, the following hard-codes that preference (i.e. “when in doubt, assume the “USA”):

int defaultcontext = convertTerritoryNameTCode("USA",0);

const char* userinput = "IN VY.HV";

double lat, lon;

int err = convertMapcodeToLatLon(&lat, &lon, userinput,

defaultcontext);

if (err)

printf("\"%s\" is not a valid mapcode\n", userinput);

else

printf("\"%s\" represents %0.6f,%0.6f\n", userinput, lat, lon);

Output:

"IN VY.HV" represents 39.727950,-86.118444

A more sophisticated system could of course make much better assumptions, for example based on the GPS coordinate of the user, or the current cursor position on a world map that is being displayed to the user.

In an interactive system, the best way to handle ambiguity is probably to always use the most recent successful, explicitly stated context as default.

For example, suppose you remembered the previous correctly interpreted user input:

const char* previous_successful_input = "RU-IN DK.CN0";

then the following code snippet will correctly interpret the completely abbreviated mapcode “49.4V” as being in the same state (i.e. RU-IN):

int previouscontext = convertTerritoryNameToCode(

previous_successful_input,0);

const char* userinput = "D6.58";

int err = decodeMapcodeToLatLon(&lat, &lon, userinput,

previouscontext);

Output:

"D6.58" represents 43.259275,44.771980

which is in Ingushetia Republic. And in fact, had we written

userinput=“AL D6.58”

this would generate the output

"AL D6.58" represents 51.958335,85.975322

which is in the Russian republic of Altai: because of the context RU-IN, the territory has been interpreted as RU-AL, instead of the equally likely US-AL (Alabama, USA) or BR-AL (Alagoas, Brazil).

Here is an example that decodes consecutive user inputs, some of them wildly ambiguous. With the exception of the very first input, all are probably interpreted as the user intended:

int previouscontext = -1; // no initial context

const char* userinput[] = {

"49.4V",

"US-IN 49.4V",

"49.4V",

"AL 49.4V",

"RU-IN 49.4V",

"AL 49.4V",

"NLD XXX.YYY",

"49.4V",

"CCCCC.CCCC",

"49.4V",

NULL

};

int i;

for (i = 0; userinput[i] != 0; i++) {

double lat, lon;

int err = decodeMapcodeToLatLon(&lat, &lon, userinput[i],

previouscontext);

if (err)

printf("\"%s\" is not a valid mapcode\n", userinput[i]);

else {

int newcontext = convertTerritoryNameToCode(userinput[i], 0);

if (newcontext>1 && (newcontext < MAX_MAPCODE_TERRITORY_CODES))

previouscontext = newcontext;

printf("%12s represents %0.6f,%0.6f\n", userinput[i], lat, lon);

}

}

Output:

"49.4V" is not a valid mapcode

US-IN 49.4V represents 39.783750,-86.198832

49.4V represents 39.783750,-86.198832

AL 49.4V represents 33.532750,-86.836184

RU-IN 49.4V represents 43.249285,44.741353

AL 49.4V represents 51.927091,85.910319

NLD XXX.YYY represents 51.204536,5.541607

49.4V represents 52.376514,4.908542

CCCCC.CCCC represents -16.326209,-48.016851

49.4V represents 52.376514,4.908542

Explanation:

"49.4V" is not a valid mapcode

Since there is no previous context, this ambiguous mapcode can simply not be interpreted. For this reason, it may be a good idea to choose a better default context than previouscontext=-1 (e.g. based on the user’s GPS position).

US-IN 49.4V represents 39.783750,-86.198832

A complete and unambiguous mapcode, it results in a coordinate in Indiana, USA.

49.4V represents 39.783750,-86.198832

Since the previous input was in Indiana, this incomplete mapcode is encoded in the same context.

AL 49.4V represents 33.532750,-86.836184

Since the previous input was in the Indiana, USA, the context “AL” is interpreted as another state in the USA, and thus results in a coordinate in Alabama (rather than, say, the state of Alagoas in Brazil).

RU-IN 49.4V represents 43.249285,44.741353

A complete and unambiguous mapcode, it results in a coordinate in Ingushetia, Russia.

AL 49.4V represents 51.927091,85.910319

Unlike two inputs back, AL 49.4V is now interpreted in Russia (the Altai Republic) rather than in the USA (Alabama), since the most recent context was Russian.

NLD XXX.YYY represents 51.204536,5.541607

A complete and unambiguous mapcode, it results in a coordinate in The Netherlands.

49.4V represents 52.376514,4.908542

Since the previous input was in The Netherlands, this time 49.4V is interpreted in The Netherlands as well.

CCCCC.CCCC represents -16.326209,-48.016851

A complete and unambiguous international mapcode. Although it decodes to a coordinate somewhere in Brazil, the mapcode does not explicitly specify Brazil as a context. Therefore, the context for future inputs will remain “The Netherlands”.

49.4V represents 52.376514,4.908542

Since the most recent explicit context was in The Netherlands, this ambiguous mapcode is now also interpreted in The Netherlands.

2.1 Recognizing an input as a mapcode

Sometimes you may wish to allow a user to input something in a “general” search box – an address, a coordinate, a mapcode, or something else.

The following routine is very efficient and lightweight, and recognizes a user input that is intended as a mapcode. For example:

“NLD 503.XE2”

is intended as a mapcode (although it happens to be invalid), while

“St. Jacobs Street 45, London”

Is not. Since anything that looks like a mapcode is very unlikely to represent anything else, we would recommend to handle (i.e. decode) anything that looks like a mapcode as a mapcode. If it fails to decode, you could still try to interpret as something else, but as has been said: it is very unlikely it does represent something else.

int compareWithMapcodeFormat(

const char* string ,

int includesTerritory)

input:

• check: a “free-form” user input
• includesTerritory: an integer: if you pass 1, full mapcodes (including optional territory context) will be recognized, i.e. inputs of the form
  [whitespace] [xxx[-yyy]] [whitespace] PPP.QQQ [-RR] [whitespace]
  If you pass 0, only “proper” mapcodes will be recognized:
  [whitespace] PPP.QQQ [-RR] [whitespace]

output:

• returns 0 if the string looks like a full/proper mapcode
• return negative in case of error (the special value -999 is returned if the string looks like a partial mapcode, i.e. might become a valid mapcode if some more characters were added).

2.2 Extra precision

Mapcodes are intended for easy, daily use. They were therefore made short, and no more precise than is necessary to be useful at the “human” scale: accurate to within 5 meters – or put another way: inaccurate by up to 5 meters. On average, inaccurate by 2.5 meters. An inaccuracy, by the way, both in latitude and longitude.

For special applications – e.g. for internal storage of original latitude/longitude pairs – mapcode was extended to allow one or two extra letters. One letter extra decreases the worst-case inaccuracy to about 1 meter, two letters decreases it to about 20 centimeters.

As an example, consider coordinate 52.376496, 4.908583. When encoded, it yields mapcode NLD 49.4V. This mapcode decodes back into 52.376514, 4.908542, a coordinate which is 2.83 meters off to the west, and 1.94 meters too far north (in combination, the mapcode is 3.44 meters away from the original coordinate).

When we encode the same coordinate with an extra digit, we get NLD 49.4V-R, a mapcode that decodes into 52.376491, 4.908574, only 96 centimeters off. With two extra digits, we get a mapcode that is about 13 centimeters off.

Mapcode: decodes into: error vs original coordinate:

49.4V 52.376514, 4.908542 3.44 meter

49.4V-R 52.376491, 4.908574 0.96 meter

49.4V-R5 52.376497, 4.908584 0.13 meter

Note that this is just an example. Had we encoded 52.376514, 4.908542, the mapcode 49.4V would be 100% precise. It is not the actual error, but the maximum error that is reduced by adding extra letters to a mapcode.

PLEASE NOTE: the above may make it seem that it is a good idea to always add extra letters. This would defeat the core purpose of the mapcode system, which is to be accurate enough for daily, human-scale use. The high-precision extension was made for very special applications only. What it may also be useful for is for internal storage, e.g. when your original coordinates are that precise, you could consider storing the precise mapcodes in your database in high-precision format. We still recommend that you display normal mapcodes (i.e. without the extension) to the end-users of your system!

3. Routines related to territories

The mapcode system is based on an official code table, which in turn is based on the ISO 3166 standards.

For efficiency, these codes need to be converted into internal “territory codes”. For these, the following three support routines are relevant:

int convertTerritoryNameToCode(

const char* isoName,

int parentTerritoryCode)

• isoName: a 2- or 3-letter “ISO standard” code of a country or a state, or a combination of country and state separated by a hyphen or space.
  Examples: “USA”, “CA”, “US-CA”, “USA-CA”, “US CA”
• parentTerritoryCode: optional territory code to help the routine choose when the abbreviation is ambiguous, which can happen if the abbreviation is of a state and the state’s country is omitted. For example, “AL” might mean either “US-AL” or “BR-AL”.
• Returns: the territory code (1-999), or negative if not no match was found.

const char* convertTerritoryCodeToIsoName(

int territoryCode,

int format)

• territoryCode – a territory code (1-999)
• format – specifies the format of the return value:
• 0 – return in unambiguous full format: “XXX” for a country, “XX-YY” for a state
• 1 – short format: “XXX” or “XX”; especially when a 2 letter (state) code is returned, although always unique within its country, it may not be unique in the world
• Returns: a pointer to a string (which will be overwritten by the next call to convertTerritoryCodeToIsoName). Returns an empty string if territoryCode or format is illegal).

int getCountryOrParentCountry(int territoryCode)

• territoryCode – territory code (1-999)
• returns:
• -1: if tc is invalid,
• the parent country of tc if tc is a valid state code
• tc: if tc is a valid country code

4. Routines related to Unicode and/or foreign alphabets

const char* decodeToRoman(const UWORD* string);

Mapcodes may be specified in other alphabets. This routine converts a 16-bit user input (i.e. a string of 16-bit Unicode characters) into a roman equivalent – which can then be offered to mc2coord;

Note that the return pointer will be overwritten by the next call to decode_to_roman.

const UWORD* encodeToAlphabet(

const char* mapcode,

int alphabet);

This routine converts a normal (roman-alphabet) mapcode into a Unicode string in the specified alphabet. For example, it can converty

PQ.RS to नप.भम (hindi alphabet)

PQ.RS to РФ.ЯЦ (Russian alphabet)

Note that the return pointer will be overwritten by the next call to encode_to_alphabet.

At the date of writing, the following 4 alphabets have been approved for official use, the others have not yet officially been approved.

0 = roman,

2 = cyrillic,

4 = hindi,

12 = gurmukhi

Version history

1.25 initial release to the public domain

1.26 added alias OD ("Odisha") for indian state OR ("Orissa")

1.27 improved (faster) implementation of the function isInArea

1.28 bug fix for the needless generation of 7-letter alternatives

to short mapcodes in large states in India

1.29 also generate country-wide alternative mapcodes for states

1.30 updated the documentation and extended it with examples and suggestions

1.31 added lookslikemapcode();

1.32 added coord2mc1();fixed 1.29 so no country-wide alternative is produced
in edge cases; prevent FIJI failing to decode at exactly 180 degrees;

1.33 fix to not remove valid results just across the edge of a territory;

improved interface readability and renamed methods to more readable forms.

1.40 added extraDigits parameter so that high-precision mapcodes can be generated