For More Information About Mapcodes, and the Latest Version of This Tool

Mapcode.exe version 2.4.1

Copyright ©2003-2016 by the Mapcode Foundation

For more information about mapcodes, and the latest version of this tool,

please visit .

Mapcode.exe may be used free of charge, and may be freely distributed
in unmodified form as long as this documentation is included.

Mapcode.exe is provided "as is", without warranty of any kind, either express or implied including, but not limited to, any implied warranty against infringement of third parties property rights, of merchantability and fitness for a particular purpose. The entire risk as to the use, quality, and performance of the tools is with you. In no event, will the creators or distributors of this tool be liable for any incidental, consequential, direct or indirect damages including but not limited to the loss of data, loss of profits, or any other financial loss arising from the use of, or inability to use the tools, even if you have been notified of the possibility of such damages.

About this software

Mapcode.exe is a small Microsoft Windows console application that can add mapcodes to a database, or add decoded mapcodes (i.e. coordinates) to a database.

Example use

Below is a piece of a spreadsheet. Some of its records specify a longitude and latitude (the second and third columns). The spreadsheet also has a column to store mapcodes (the 5th column) but these cells are not yet filled in.

A / B / C / D / E
1 / Name / latitude / longitude / ISO / Mapcode
2 / Palace / 52.3732 / 4.8919
3 / Airport / 52.3087 / 4.7624
4 / Central Square
5 / Central Station / 52.378 / 4.9

In order to add mapcodes to this spreadsheet, take the following steps:

1. export your spreadsheet (for example, as a comma-delimited CSV file called mydata.csv)
2. runMapcode.exe with the appropriate arguments. In this case we want to readthe latitude from the second column (B), the longitude from the third column (C), and write the mapcode to 5thcolumn (E).The results are to be stored in a file called newdata.csv:

Mapcode.exe–e -hmydata.csv newdata.csv 2 35

or, if you prefer:

Mapcode.exe –e -h mydata.csv newdata.csv B C E

If you now open newdata.csv in your spreadsheet, you will see that (where possible), the mapcode field was filled in.

A / B / C / D / E
1 / Name / latitude / longitude / ISO / mapcode
2 / Palace / 52.3732 / 4.8919 / VHXG9.RM02
3 / Airport / 52.3087 / 4.7624 / VHWK5.H7KH
4 / Central Square
5 / Central Station / 52.378 / 4.9 / VHXG9.WH9C

However, note that all mapcodes are 9-character “international” codes.This can sometimes be appropriate, but usually you have a clear context. For example, if you operate only in The Netherlands, you might call

Mapcode.exe –e -h mydata.csv newdata.csv 2 3 5 4 NLD

Or, if you prefer:

Mapcode.exe –e -h mydata.csv newdata.csv B CED NLD

This line specifies that Mapcode.exe should look in coulumn 4 for context, or, if that column is empty, use “NLD” as context. (NLD is the 3-letter code for The Netherlands, from ISO standard 3166-1 alpha-3)

The result would now be:

A / B / C / D / E
1 / Name / latitude / longitude / ISO / mapcode
2 / Palace / 52.3732 / 4.8919 / NLD / 2N.9F
3 / Airport / 52.3087 / 4.7624 / NLD / 8G.2GX
4 / Central Square
5 / Central Station / 52.378 / 4.9 / NLD / 3F.ST

Note that the codes are significantly shorter. Also note that whenever the 4th column was blank, the appropriate ISO code was filled in.

Reference manual

The input file

The input file must be an ASCII or UTF-8 text file. Each line of the text file should contain a single record, and the fields of the record should be separated by either commas, semicolons, or tabs.

Mapcode.exe expects the file to be comma-separated, but you can override this with

-tspecifies that the input fields are tab-delimited

-cspecifies that the input fields are comma-delimited (superfluous)

-s;specifies that the input fields are semicolon-delimited

-s/specifies that the input fields are slash-delimited

-s9specifies that the input fields are delimited by ascii code 9

The output file

The output will be written to another text file. You should not specify the same file as is used for input.

The output file will be a text file in the same format as the input file, unless you specify

-fforce output to be comma-delimited

-f;force output to be semicolon-delimited

-f9force output to be tab-delimited (i.e. ascii code 9)

The fields

Mapcode.exe is called as follows:

MAPCODEoptions infile outfile latcol loncol codecol [isocol [defaultiso]]

Options start with a hyphen, and can actually occur anywhere in the argument list. At least one option (–d or –e) must be specified (see below).

Apart from the input file infile and the output file outfile, three columns in the input/output files must be specified:

latcol:the column where to read or write the latitude

loncol:the column where to read or write the longitude

codecol:the column where to read or write the mapcode

One or two extra, optional arguments can be added:

isocol:the column where to read or write the territory ISO code(pass 0 if this column is not required)

defaultiso:a string (e.g. “NLD” or “USA-CA”) indicating a default territory ISO when the isocol is 0 or when the isocol column is empty

Coding option: encoding or decoding?

You must specify whether you wish to encode coordinates into mapcodes, or decode mapcodes into coordinates:

-eencode coordinates into mapcodes

-ddecode mapcodes into coordinates

Advanced options

High-precision encoding (-1 and -2)

Mapcodes were designed for human-scale everyday use. Normal mapcodes are therefore accurate to roughly 5 meters. By adding some extra characters to a mapcode (separated by a hyphen), locations can be specified more precisely.

-1adds one character to the mapcodes, leading to roughly 1-meter accuracy

-2adds two characters to the mapcodes, leading to roughly 20-cm accuracy

Restrict encodes to the specified territory (-r)

Restrict encoding to only those coordinates that can be encoded within the ISO context specified (i.e. in the ISO column of your data or in your defaultiso argument).

If you do not set –r, coordinates out of the specified context are encoded as 9-character “world” mapcodes.

-rrestrict encodes to the specified ISO context (only works with –e)

Overwrite target fields (-o)

Normally, mapcode.exe will only write to a field if it is still empty. This allows you to, for example, erase all the “world” mapcodes in your database for addresses in Belgium, then run mapcode.exe with “BEL” as default ISO.

The –o option, on the other hand, forces mapcode.exe to clear ALL cells, and fill them (where possible) with new results.

-ooverwrite target fields

Integrate mapcode and territory into a single field (-i)

When encoding, the –i option forces the ISO code of the territory to be integrated into the mapcode field.

-iencode ISO code into the mapcode field

Note: 9-character mapcodes (so-called “world mapcodes”) are independent of context. For these, no ISO code is integrated.

Skip header line(-h)

If your database has a header line, this option excludes it from the conversion.

-hexclude first line from the conversion

-h123exclude first 123 lines from the conversion

Quiet (-q) / Wait (-w)

Normally, when processing a csv file, mapcode.exe shows a progress percentage, followed by a few lines of results.

–qsuppresses the progress and results

-wpause when done until the user presses ENTER (unless –q specified)

Adjust coordinates (-a)

This options will adjust the latitude and longitude by a specified number. For example, if your database stores coordinates in millionths of degrees (instead of degrees), specify

-a1000000

When encoding coordinates into mapcodes, this will divide the latitude and longitude by a million. When decoding, it will generate latitudes and longitudes that are multiplied by a million.

Version history

Version 1.0

• Original release

Version 1.32

• Allow columns to be specified not just as a number (1,2,3…) but also as a typical spreadsheet label (A,B,C…)
• Added the –a option (for coordinates specified in e.g. millionths of degrees)

Version 1.41

• Re-Compiled based on C version v1.41 (added the new state IN-TG in India)

Version 1.50

• Re-Compiled based on C version v1.5 (added Greek encoding, retired some legacy territories such as AU-JB, EAZ and SKM)

Version 2.0

• Major change, some territories redefined. Allow micrometer precision

Version 2.2

• Minor change, fixed some micro-degree gaps between territories, noticeable now high-precision has been implemented

Version 2.4.1

• Latest build; speed improvements