Skip to content

Commit

Permalink
Merge pull request #1 from mapcode-foundation/dev-1.50
Browse files Browse the repository at this point in the history 
Moved dev-1.50 to master
  • Loading branch information
@rijnb
rijnb committed May 22, 2015
2 parents c78d1b9 + 9845151 commit f310691
Show file tree
Hide file tree
Showing 33 changed files with 5,089 additions and 249 deletions.
2 changes: 1 addition & 1 deletion NOTICE
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,6 @@ MAPCODE JAVA LIBRARY
-------------------------------------------------------------------------------

Original C library created by Pieter Geelen. Work on Java version
of the Mapcode library by Rijn Buve and Matthew Lowden.
of the Mapcode library by Rijn Buve (original port by Matthew Lowden).

Copyright (C) 2014-2015 Stichting Mapcode Foundation (http://www.mapcode.com)
76 changes: 52 additions & 24 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,53 +7,81 @@ Available methods:

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

GET /mapcode/codes/{lat},{lon} [/mapcodes|local|international] [?precision=[0|1|2]&territory={territory}&include={offset|territory}]
Convert latitude/longitude to one or more mapcodes.
GET /mapcode/codes/{lat},{lon}[/[mapcodes|local|international]]
[?precision=[0|1|2] & territory={restrictToTerritory} & alphabet={alphabet} & include={offset|territory}]

Convert latitude/longitude to one or more mapcodes.
Path parameters:
lat : latitude, range [-90, 90]
lon : longitude, range [-180, 180] (mapped if outside range)
lat : latitude, range [-90, 90]
lon : longitude, range [-180, 180] (mapped if outside range)

An additional filter can be specified to limit the results:
all : same as without specifying a filter, returns all mapcodes
local : return the shortest local mapcode
international : return the shortest international mapcode
all : same as without specifying a filter, returns all mapcodes
local : return the shortest local mapcode
international : return the shortest international mapcode

Query parameters:
precision : precision, range [0, 2] (default=0)
territory : territory context, numeric or alpha code
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'
precision : precision, range [0, 2] (default=0)
territory : territory to restrict results to, numeric or alpha code
alphabet : Alphabet to return results in, numeric or alpha code
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'

GET /mapcode/coords/{mapcode} [?territory={code}]
GET /mapcode/coords/{code} [?territory={mapcodeTerritory}]
Convert a mapcode into a latitude/longitude pair

Path parameters:
territory : territory context, numeric or alpha code
Path parameters:
territory : territory context, numeric or alpha code
code : mapcode code (local or international)
Query parameters:
territory : mapcode territory, numeric or alpha code

GET /mapcode/territories [?offset={offset}&count={count}]
Return a list of all valid numeric and alpha territory codes.
Return a list of all territories.

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

Path parameters:
territory : territory to get info for, numeric or alpha code

Query parameters:
offset : return list from 'offset' (negative value start counting from end)
count : return 'count' items at most
territoryContext: territory context (optional, for disambiguation)

GET /mapcode/territories/{code}
Return information for a single territory code.
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:
territory : territory context, numeric or alpha code

alphabet : alphabet to get info for, numeric or alpha code

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

To build and run the REST API, type:

mvn clean install
mvn jetty:run (alternatively, you can use: mvn tomcat7:run)


If you wish to use MongoDB tracing, will need to provide your own local
*secret* properties file, called `mapcode-secret.properties`, for example
in `src/main/resources` which override the following properties:

MongoDBTrace.writeEnabled = true
MongoDBTrace.servers = your-server:27017
MongoDBTrace.userName = your-username
MongoDBTrace.password = your-password

The service will work without this, but will not trace events to the
database.

Try out if the web services work by entering the following URL in your web browser
(this should show you a HTML help page):

Expand Down
151 changes: 125 additions & 26 deletions example/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@
margin: 5px 10px 5px 10px;
font-family: verdana, geneva, arial, helvetica, sans-serif;
font-size: 12px;
background-color: #ddeeff;
background-color: #eeeeee;
text-decoration: none;
font-weight: normal;
line-height: normal;
Expand All @@ -33,12 +33,11 @@
<body onload="onLoad()">
<h1>Sample HTML/Javascript using the mapcode REST API</h1>

This page is an example of how the mapcode REST API can be used from HTML/Javascript (or
other languages, for that matter). You can look at the source code of this page to see
how the REST API is called from Javascript, or you can try it out by simply entering some
information in the dialog boxes and pressing the conversion/request buttons.
<br/>
<br/>
This page is an example of how the mapcode REST API can be used from HTML/Javascript.
You can have a look at the source code of this page to see how the REST API is called,
r you can try it out by simply entering some information in the dialog boxes and
pressing the conversion/request buttons.

<b>Copyright (C) 2015, Stichting Mapcode Foundation</b>, <a href="http://www.mapcode.com">http://www.mapcode.com</a>

<hr/>
Expand All @@ -64,7 +63,8 @@ <h2>REST API Version</h2>
<script type="text/javascript">

/* This is the base URL of the mapcode REST API. */
var apiBaseURL = "http://mapcode.buve.info/mapcode";
var apiBaseURL = "http://api.mapcode.com/mapcode";

// For local testing, use:
// var apiBaseURL = "http://localhost:8080/mapcode";

Expand Down Expand Up @@ -98,7 +98,7 @@ <h2>REST API Version</h2>
}

function createTerritoryLine(territory) {
var line = "<b>" + territory.territoryNameInternational + "</b> (" + territory.territoryCode + ") - <u>" + territory.fullName + "</u>";
var line = "<b>" + territory.name + "</b> (" + territory.code + ") - <u>" + territory.fullName + "</u>";
if (territory.fullNameAliases) {
for (j = 0; j < territory.fullNameAliases.length; j++) {
line += ", " + territory.fullNameAliases[j];
Expand All @@ -112,6 +112,10 @@ <h2>REST API Version</h2>
}
return line;
}

function createAlphabetLine(alphabet) {
return "<b>" + alphabet.name + "</b> (" + alphabet.code + ")</u>";
}
</script>

<!--
Expand All @@ -126,10 +130,14 @@ <h2>REST API Version</h2>

/* Use the input fields to build the request URL. */
var territory = document.getElementById("territoryEncode").value;
var precision = document.getElementById("precision").value;
var alphabet = document.getElementById("alphabetEncode").value;
var lat = document.getElementById("lat").value;
var lon = document.getElementById("lon").value;
var url = apiBaseURL + "/codes/" + lat + "," + lon + "?precision=0&include=territory" +
((territory && (territory.length != 0)) ? "&territory=" + territory : "");
var url = apiBaseURL + "/codes/" + lat + "," + lon + "?include=territory" +
((territory && (territory.length != 0)) ? "&territory=" + territory : "") +
((precision && (precision.length != 0)) ? "&precision=" + precision : "") +
((alphabet && (alphabet.length != 0)) ? "&alphabet=" + alphabet : "");
document.getElementById("requestEncode").innerHTML = createRequestLine(url);

/* Asynchronously request a solution, call encodeResponseReady when done. */
Expand Down Expand Up @@ -157,15 +165,21 @@ <h2>REST API Version</h2>
for (i = 0; i < result.mapcodes.length; i++) {
var isGrey = ((i > 0) && (result.mapcodes[i].territory == result.mapcodes[i - 1].territory));
if (isGrey) {
resultLines += "<font color=\"#bbbbbb\">";
resultLines += "<font color=\"#888888\">";
}
resultLines += ((result.mapcodes[i].territory == "AAA") ? "" :
result.mapcodes[i].territoryInAlphabet + " ") + "<b>" + result.mapcodes[i].mapcodeInAlphabet + "</b> ";

if (result.mapcodes[i].mapcode != result.mapcodes[i].mapcodeInAlphabet) {
resultLines += " (" + ((result.mapcodes[i].territory == "AAA") ? "" :
result.mapcodes[i].territory + " ") + result.mapcodes[i].mapcode + ") ";
}
resultLines += ((result.mapcodes[i].territory == "AAA") ? "" : result.mapcodes[i].territory) +
" <b>" + result.mapcodes[i].mapcode + "</b>";

if (result.mapcodes[i].mapcode == result.local.mapcode) {
resultLines += " (default local)";
resultLines += "(default local)";
}
if (result.mapcodes[i].territory == "AAA") {
resultLines += " (international)";
resultLines += "(international)";
}
if (isGrey) {
resultLines += "</font>";
Expand All @@ -184,15 +198,20 @@ <h2>REST API Version</h2>
<h2>Convert a coordinate (latitude, longitude) to mapcode(s)</h2>

<p>
<tt>HTTP GET /mapcode/codes/{lat},{lon}[?territory={restrictToTerritory}]</tt>
<tt>HTTP GET /mapcode/codes/{lat},{lon}[?territory={restrictToTerritory}&precision=[0|1|2]]</tt>
</p>

<form action="#" onsubmit="return encodeButtonPressed();">
<input type="text" id="lat" value="51.427624"> = latitude [-90, 90] (must be in range)
<br/>
<input type="text" id="lon" value="5.488075"> = longitude [-180, 180] (wrapped if outside of range)
<br/>
<input type="text" id="territoryEncode" value=""> = restrict results to 1 territory (empty = show all)
<input type="text" id="territoryEncode" value=""> = restrict results to 1 territory (numeric or alpha, empty = show
all)
<br/>
<input type="text" id="alphabetEncode" value=""> = alphabet used for results (numeric or alpha, empty = roman)
<br/>
<input type="text" id="precision" value=""> = precision (0, 1 or 2, empty = 0)
<br/>
<input type="button" value="Encode" onclick="encodeButtonPressed()">
</form>
Expand All @@ -215,12 +234,12 @@ <h2>Convert a coordinate (latitude, longitude) to mapcode(s)</h2>
function decodeButtonPressed() {

/* Use the input fields to build the request URL. */
var territory = document.getElementById("territoryDecode").value;
if (territory == "") {
territory = "AAA";
var context = document.getElementById("contextDecode").value;
if (context == "") {
context = "AAA";
}
var mapcode = document.getElementById("mapcode").value;
var url = apiBaseURL + "/coords/" + mapcode + "?territory=" + territory;
var url = apiBaseURL + "/coords/" + mapcode + "?context=" + context;

/* Update page. */
document.getElementById("resultDecode").innerHTML = '<font color=grey>Waiting...</font>';
Expand Down Expand Up @@ -256,11 +275,11 @@ <h2>Convert a coordinate (latitude, longitude) to mapcode(s)</h2>
<h2>Convert a mapcode to a coordinate (latitude, longitude)</h2>

<p>
<tt>HTTP GET /mapcode/coords/{code}[?territory={mapcodeTerritory}]</tt>
<tt>HTTP GET /mapcode/coords/{code}[?context={territoryContext}]</tt>
</p>

<form action="#" onsubmit="return decodeButtonPressed();">
<input type="text" id="territoryDecode" value="NLD"> = mapcode territory (empty = international)
<input type="text" id="contextDecode" value="NLD"> = mapcode territory (empty = international)
<br/>
<input type="text" id="mapcode" value="XX.XX"> = mapcode code
<br/>
Expand Down Expand Up @@ -306,8 +325,6 @@ <h2>Convert a mapcode to a coordinate (latitude, longitude)</h2>
/* Did the request succeed? */
document.getElementById("responseTerritory").innerHTML = createResponseLine(status, response);
if ((status == 200) && response) {

/* Parse the response into an array of mapcodes. */
var result = JSON.parse(response);

var resultLines = "";
Expand Down Expand Up @@ -351,5 +368,87 @@ <h2>Get territory information</h2>
<div id="requestTerritory"></div>
<div id="responseTerritory"></div>

<hr/>

<!--
~ --------------------------------------------------------------------------------
~ ALPHABET INFORMATION
~ --------------------------------------------------------------------------------
-->

<script>
function alphabetButtonPressed() {
document.getElementById("resultAlphabet").innerHTML = '<font color=grey>Waiting...</font>';

var alphabet = document.getElementById("alphabet").value;
var url = apiBaseURL + "/alphabets" + (alphabet ? ('/' + alphabet) : "");
document.getElementById("requestAlphabet").innerHTML = createRequestLine(url);

/* Asynchronously request a solution, call encodeResponseReady when done. */
var xmlhttp = new XMLHttpRequest();
xmlhttp.onreadystatechange = function () {
if (xmlhttp.readyState == 4) {
alphabetResponseReady(xmlhttp.responseText, xmlhttp.status);
}
}
xmlhttp.open("GET", url, true);
xmlhttp.send();
}

function alphabetResponseReady(response, status) {

/* Did the request succeed? */
document.getElementById("responseAlphabet").innerHTML = createResponseLine(status, response);
if ((status == 200) && response) {
var result = JSON.parse(response);

var resultLines = "";
if (result.alphabets) {
resultLines += "<b><u>List all alphabets (" + result.alphabets.length + "):</u></b></u><br/><small>";
for (i = 0; i < result.alphabets.length; i++) {
var alphabet = result.alphabets[i];
resultLines += createAlphabetLine(alphabet) + "<br/>";
}
}
else {
resultLines += "<b><u>List one alphabet:</u></b></u><br/><small>";
resultLines += createAlphabetLine(result);
}
resultLines += "<small>"
document.getElementById("resultAlphabet").innerHTML = resultLines;
}
else {
document.getElementById("resultAlphabet").innerHTML = "<b>Error</b> (status = " + status + ')';
}
}
</script>

<h2>Get alphabet information</h2>

<p>
<tt>HTTP GET /mapcode/alphabet[/{alphabet}[?context={territoryContext}]]</tt>
</p>

<form action="#" onsubmit="return decodeButtonPressed();">
<input type="text" id="alphabet" value=""> = alphabet to show info for (empty = all alphabets)
<br/>
<input type="button" value="List" onclick="alphabetButtonPressed()">
</form>

<div id="resultAlphabet"></div>
<br/>

<div id="requestAlphabet"></div>
<div id="responseAlphabet"></div>

<hr/>
<p><font color="#882222">
<b>Important:</b> The Mapcode REST API on <tt>api.mapcode.com</tt> is provided primarily
for examples and reference purposes. If you plan to use the REST API more extensively,
please consider running your own REST API server. You can find the REST API server sources
and installation notes on
<a href="https://github.com/mapcode-foundation/mapcode-rest-service" target="_blank">Github</a>.
</font></p>

</body>
</html>
Loading

0 comments on commit f310691

Please sign in to comment.