Mapcode REST API

​Stichting Mapcode Foundation biedt de Mapcode REST API aan op: 

​

• https://api.mapcode.com/mapcode

​

Dit is een gratis web service, die uitsluitend dient als voorbeeld van een mapcode web service. We proberen deze gratis service zo stabiel en goed mogelijk aan te bieden en we nodigen je vooral uit om deze uit te proberen. Houdt er echter rekening mee dat de service wellicht ooit gediscontinueerd kan worden. Lees dan ook de extra mededeling in het blauwe vlak op deze pagina.

​

Je kunt deze service proberen met curl:

​

curl -X GET https://api.mapcode.com/mapcode

​

Hiermee krijg je hulptekst te zien over het gebruik van de service. De volledige source code voor de web service is beschikbaar op:

​

• https://github.com/mapcode-foundation/mapcode-rest-service

​

Je kunt deze source gebruiken en aanpassen zo je wilt, om de web service te creëren die je zelf nodig hebt.

​

De (Engelstalige) voorbeelden hieronder laten zien hoe je de web service kunt gebruiken in je eigen cloud. Dat is bijvoorbeeld van belang als je bedrijf of dienst afhankelijk is van de mapcode service.

​

Example: converteer locatie naar mapcode

Bijvoorbeeld, om een breedtegraad/lengtegraad paar van 48.858370, 2.294481 (Eiffeltoren in Parijs) om te zetten in een kaartcode:

​

curl -X GET https://api.mapcode.com/mapcode/codes/48.858370,2.294481

​

Dit geeft:

​

{

    "international": {

        "mapcode": "VHPM8.QYCK"

    },

    "local": {

        "mapcode": "4J.P2",

        "territory": "FRA"

    },

    "mapcodes": [

        {

            "mapcode": "4J.P2",

            "territory": "FRA"

        },

        {

            "mapcode": "FH.N7T",

            "territory": "FRA"

        },

        {

            "mapcode": "H60.TKL",

            "territory": "FRA"

        },

        {

            "mapcode": "HCPW.PQV",

            "territory": "FRA"

        },

        {

            "mapcode": "VHPM8.QYCK"

        }

    ]

}

​

Het antwoord bestaat altijd uit drie delen:

• International: Dit is een wereldwijd unieke mapcode. Het is ook de langste mapcode (van in totaal 10 tekens). Gebruik deze code alleen als u geen idee heeft wat de regionale context voor een code is. Voor systemen die in een specifiek land of staat worden gebruikt, raden we aan om de kortere codes te gebruiken.

• Local: Dit is gewoon de kortste code van alle alternatieven in de sectie "Mapcodes". Houd er rekening mee dat de code een onverwachte gebiedscode kan gebruiken in de buurt van de grens, waar andere kaartcodes beschikbaar kunnen zijn voor aangrenzende gebieden.

• Mapcodes: Dit is een lijst met alle beschikbare mapcodes, inclusief de internationale, voor een specifieke locatie. Als uw systeem zich bewust is van de geografische context (bijvoorbeeld als het systeem een postcodesysteem voor een land is), dan moet u op zoek gaan naar de kortste code in deze lijst voor uw gebied en die code gebruiken.

 

Voorbeeld: converteer mapcode naar locatie

Om een internationale kaartcode terug te converteren naar een locatie, kunt u dit gebruiken:

​

http get https://api.mapcode.com/mapcode/coords/VHPM8.QYCK

Dit geeft de lengte- en breedtegraad van de locatie weer:

​

{

    "latDeg": 48.858368,

    "lonDeg": 2.2944905

}

​

Internationale codes zijn wereldwijd uniek, dus dit werkt altijd. Als u een kortere code gebruikt, die wij doorgaans aanbevelen omdat ze gemakkelijker te onthouden en te communiceren zijn, moet u het betreffende gebied opgeven als 'context' om de kaartcode te disambiguëren:

​

http get https://api.mapcode.com/mapcode/coords/4J.P2?context=FRA

​

Dit geeft:

​

{

    "latDeg": 48.85838,

    "lonDeg": 2.29444

}

​

Het kan zijn dat u merkt dat de geretourneerde locaties niet precies dezelfde zijn. Dit komt omdat de roosters die gebruikt worden voor de internationale en kortere codes verschillend zijn. De geretourneerde locaties liggen echter altijd zeer dicht bij elkaar (binnen 5 meter).

​

Voorbeeld: deploy op Amazon Elastic Beanstalk

Als u de Mapcode REST API op Amazon wilt deployen, raden wij u aan om Elastic Beanstalk te gebruiken.  In dit gedeelte wordt in grote lijnen beschreven hoe u dit moet doen.

​

Voorwaarden voor het gebruik van de service zijn:

• Maven

• JDK 8 or higher

• Amazon AWS account

​

U kunt de Mapcode REST API-binaire bestanden maken en deze als volgt inzetten:

​

Haal de source code voor de Mapcode REST API op:

• https://github.com/mapcode-foundation/mapcode-rest-service/releases

​

Compileer de broncode en maak een WAR-bestand met behulp van:

​

cd <source-dir>

mvn clean install

​

Hert build process moet eindigen met de boodschap "BUILD SUCCESS".

 

Log in bij Amazon AWS en ga naar het Serv ices menu en kies Elastic Beanstalk.  Kies dan Actions en Create environment.

​

Maak een Elastic Beanstalk mgeving met de volgende minimale configuratie:

 

• 2 or more instances

• Recommended EC2 instance type: t2.micro or more higher

• Platform: Tomcat running on 64bit Linux 

• No additional disk storage or databases required

• Environment type: load balancing, auto scaling

• Availability zones: any

• Monitor interval: 1 minute

• Health path: /mapcode/status

• Ignore HTTP 4xx: enabled

• Deployment policy: rolling

​

Deploy het Mapcode REST API WAR-bestand naar Elastic Beanstalk, dat zich bevindt op:

​

<source dir>/deployment/target/deployment-x.y.z.war

​

U zou nu toegang moeten hebben tot de Mapcode REST API via de URL van Elastic Beanstalk (bijv. my-mapcode.elasticbeanstalk.com).