+ +

Javascript library to convert +between mapcodes and latitude/longitude

+ +

Version 1.32

+ +

Copyright �2003-2014 by The Mapcode Foundation

+ +

1. Converting a coordinate into a mapcode

+ +

function master_encode(lat,lon,ccode)

+ +

lat,lon: +latitude and longitude (in degrees)

+ +

ccode: +a country code, an integer between 0 and MAX_CCODE

+ +

returns: +an array of result pairs

+ +

Generates possible mapcodes for the given +coordinates in the given territory.

+ +

Returns an array of pairs [ mapcode, ccode ] where mapcode is a clean mapcode (a string +with a prefix and postfix separated by a dot), and ccode is the country context of the mapcode.

+ +

Example code:

+ +

var ccode = iso2ccode('US-CA');

+ +

var a = +master_encode( 34.00956,-118.210572, ccode );

+ +

document.write( +a.length+' results: ');

+ +

for( var +i=0;i<a.length;i++)

+ +

document.write(ccode2iso(a[i][1],2),' +',a[i][0],' ');

+ +

Output:

+ +

5 results:

+ +

CA XX.XX

+ +

CA BP.HKL

+ +

CA L1Y.VMC

+ +

CA 94NG.LH3

+ +

CA KKYP.19MN

+ +

2. Converting a mapcode into a coordinate

+ +

function master_decode(mapcode,ccode)

+ +

mapcode: a string containing a mapcode

+ +

ccode: +a country code, an integer between 0 and MAX_CCODE

+ +

returns: +an object with fields y (latitude) and x (longitude), or false

+ +

Example code:

+ +

var ccode = iso2ccode('NLD');

+ +

var result = +master_decode( '49.4V', ccode );

+ +

document.write( +result.y+','+result.x );

+ +

Output:

+ +

52.376514, 4.908542

+ +

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 �country codes� (values from 0 to MAX_CCODE). For +these, the following routines are relevant:

+ +

function set_disambiguate(isocode)

+ +

isocode: +a string, e.g. �US-CA� for California, �NLD� for The Netherlands

+ +

returns: +nonzero if isocode does not allow +states to be disambiguated

+ +

function iso2ccode(isocode)

+ +

isocode: +a string, e.g. �US-CA� for California, �NLD� for The Netherlands

+ +

returns: +a country code, an integer between 0 and MAX_CCODE

+ +

function ccode2iso(ccode,international)

+ +

ccode: +a country code, an integer between 0 and MAX_CCODE

+ +

returns: +a string

+ +

The international +argument specifies how to generate strings for the 8 countries (USA, India, Canada, +Australia, Mexico, Brazil, Russia, China) that allow state/province mapcodes:

+ +

If international=2, + the shortest possible internationally unambiguous string is returned: the + country is left out if the state is internationally unambiguous.
If international=1, + the full string is always returned: the country is included even when the + state is internationally unambiguous.
If international=0, + a nationally unambiguous string is + returned: the country is always left out if a state is provided. This may be ambiguous internationally, + so this option should only be used for systems that are 100% national in + scope!

+ +

When in doubt, pass �2�.

+ +

Example code:

+ +

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

+ +

var ccode1 += iso2ccode('US-CA');

+ +

var ccode2 += iso2ccode('US-IN');

+ +

document.write( +"international=", i, ":" ,

+ +

ccode2iso(ccode1,i), +" , ",

+ +

ccode2iso(ccode2,i), +" " );

+ +

}

+ +

Output:

+ +

international=0:CA +, IN
+international=1:US-CA , US-IN
+international=2:CA , US-IN

+ +

As you can see:

+ +

International=1 always includes �US-�, even +in the case of CA (California) since no other country or state has CA as its abbreviation.

+ +

International=2 only includes �US-� for the +state of IN, since IN on its own is ambiguous: it could mean Indiana, USA or the Ingushetia Republic, Russia.

+ +

International=0 just abbreviates to the +state, so the correct interpretation of �IN� depends on the system knowing what +the country context is.

+ +

function StateParent(ccode)

+ +

ccode: +a country code, an integer between 0 and MAX_CCODE

+ +

returns: +a country code, an integer between 0 and MAX_CCODE

+ +

function fullname(ccode)

+ +

ccode: +a country code, an integer between 0 and MAX_CCODE

+ +

returns: +string

+ +

function isState(ccode)

+ +

ccode: +a country code, an integer between 0 and MAX_CCODE

+ +

returns: +true or false

+ +

function hasStates(ccode)

+ +

ccode: +a country code, an integer between 0 and MAX_CCODE

+ +

returns: +true or false

+ +

function find_bestiso(y,x,preferred preferred_ccode iso)

+ +

y,x: +latitude and longitude in degrees

+ +

preferred_ccode: +a country code, an integer between 0 and MAX_CCODE

+ +

returns: +a country code, an integer between 0 and MAX_CCODE

+ +

4. Routines related to Unicode and/or foreign alphabets

+ +

function to_ascii( userinput )

+ +

userinput: +a string

+ +

Mapcodes may be specified in other +alphabets. This routine takes a UNICODE user input and returns its roman roman +equivalent – which can then be offered to decode_mapcode.

+ +

Characters that have no roman equivalent in +the mapcode system are replaced by question marks.

+ +

function showinlan( romanMapcode, alphabetNr, asHTML )

+ +

romanMapcode: +a string

+ +

alphabetNr: +an integer

+ +

asHTML: +optional, pass true to build the string in HTML format

+ +

This routine converts a normal +(roman-alphabet) mapcode into a string in the specified alphabet.

+ +

Example code:

+ +

document.write( +showinlan( �PQ.RS�, 4 ) ,� �)

+ +

document.write( +showinlan( �PQ.RS�, 2 ) ,� �)

+ +

Output:

+ +

नप.भम

+ +

РФ.ЯЦ

+ +

The following alphabets have been approved +for official use, other values are available but have not yet officially been formally +approved. Please check www.mapcode.com to +see if there is a more up-to-date version.

+ +

0: roman

+ +

2: cyrillic

+ +

4: hindi

+ +

12: gurmukhi

+ +

-Welcome to GitHub Pages.

-Designer Templates

-Rather Drive Stick?

-Authors and Contributors

-Support or Contact

mapcode-js

Mapcode Library for JavaScript

+Welcome to GitHub Pages.

+Designer Templates

+Rather Drive Stick?

+Authors and Contributors

+Support or Contact

mapcode-js

Mapcode Library for JavaScript

1. Converting a coordinate into a mapcode

2. Converting a mapcode into a coordinate

3. Routines related to territories

4. Routines related to Unicode and/or foreign alphabets