+
+
Javascript library to convert
+between mapcodes and latitude/longitude
+
+
+
+
Version 1.41
+
+
+
+
Copyright 2003-2015 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:<br>');
+
+
for( var
+i=0;i<a.length;i++)
+
+
document.write(ccode2iso(a[i][1],2),'
+',a[i][0],'<br>');
+
+
+
+
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),
+"<br>" );
+
+
}
+
+
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 ) ,<br>)
+
+
document.write(
+showinlan( PQ.RS, 2 ) ,<br>)
+
+
+
+
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
+
+
+
+