ARCHIVE – Web API (v3.1.1 or lower only)

Maps Marker Pro offers an integrated API which allows you to manage your markers and layers through a highly customizable Web API, which supports GET & POST requests, JSON & XML as formats and was developed with a focus on security. If you created a cool application based on the MapsMarker API let us know and we will add it to our showcases! Index

• Endpoint
• Authentication
  • Enabling API and setting public & private API key
  • Required authentication request parameters
  • PHP sample code for generating signatures
  • JavaScript sample code for generating signatures
  • C# sample code for generating signatures
  • API URL generator and API URL Tester
• Available request methods
• Available action parameters
• Available type parameters
• Global parameters (for all API actions)
• Available parameters for type marker
• Available parameters for type layer
• Special parameters for search action
• Additional security options
• Response
• Examples
  • GET requests
  • POST requests

Endpoint

• Free version: https://www.your-domain.com/wp-content/plugins/leaflet-maps-marker/leaflet-api.php
• Pro version (<= version 2.9): https://www.your-domain.com/wp-content/plugins/leaflet-maps-marker-pro/leaflet-api.php
• Pro version (>= version 3.0): https://www.your-domain.com/maps/webapi/

It is highly recommended to use https only for accessing the Web API, as otherwise the secret token could be intercepted by third parties while being transmitted in cleartext via http!

back to index

Authentication

All requests must be authenticated using an expiring signature. This is similar to the approach used by Amazon to secure access to their S3 Storage API. Once authenticated, all activated API actions can be executed. In addition to the security measures enforced by the API, it’s strongly advisable to implement SSL for the WordPress site (beyond the scope of this API).

Enabling API and setting public & private API key

In order to use your API, you first have to set the API status to enabled by navigating to Settings / Misc / MapsMarker API settings: As next step you have to set a public and private API key:

IMPORTANT: Keep the private key secret. It must not be shared in any way and it must not be included in any links or transferred across the wire. It is used exclusively to calculate the signature for each API request. As next step do not forget to save the settings. back to index

Required authentication request parameters

Each request at a minimum must include the following 3 query parameters;

• api_key – The public API key defined on the settings page / misc / MapsMarker API settings – e.g. “1234”
• expires – Expiration date for the request expressed as a UNIX timestamp in seconds e.g. 1369749344
• signature – A url-encoded, base64 HMAC-SHA1 hash of a colon separated string following this structure:

  {api_key}:{expires}

  e.g. 1234:1369749344

  The signature for this request using the private key of “abcd” is XlWau4wu3UBPUZbBeCXuyDxzg7g%3D

Complete example request: http://yourdomain.com/wp-content/plugins/leaflet-maps-marker/pro/leaflet-api.php?key=1234&signature=XlWau4wu3UBPUZbBeCXuyDxzg7g%3D&expires=1369749344 back to index

PHP sample code for generating signatures

<?php function calculate_signature($string, $private_key) { $hash = hash_hmac("sha1", $string, $private_key, true); $sig = rawurlencode(base64_encode($hash)); return $sig; } $api_key = "1234"; $private_key = "abcd"; $expires = strtotime("+60 mins"); $string_to_sign = sprintf("%s:%s", $api_key, $expires); $sig = calculate_signature($string_to_sign, $private_key); var_dump($sig); ?> back to index

JavaScript sample code for generating signatures

<script src="https://crypto-js.googlecode.com/svn/tags/3.1.2/build/rollups/hmac-sha1.js"></script> <script src="https://crypto-js.googlecode.com/svn/tags/3.1.2/build/components/enc-base64-min.js"></script> <script type="text/javascript"> function CalculateSig(stringToSign, privateKey){ var hash = CryptoJS.HmacSHA1(stringToSign, privateKey); var base64 = hash.toString(CryptoJS.enc.Base64); return encodeURIComponent(base64); } var d = new Date, expiration = 3600 // 1 hour, unixtime = parseInt(d.getTime() / 1000), future_unixtime = unixtime + expiration, publicKey = "1234", privateKey = "abcd", stringToSign = publicKey + ":" + future_unixtime; sig = CalculateSig(stringToSign, privateKey); console.log(sig); </script> back to index

C# sample code for generating signatures

using System; using System.Web; using System.Security.Cryptography; using System.Text; namespace MapsMarkerPro { public class Sample { public static GenerateSignature() { string publicKey = "1234"; string privateKey = "abcd"; string expires = Security.UtcTimestamp(new TimeSpan(0,1,0)); string stringToSign = string.Format("{0}:{1}", publicKey, expires); var sig = Security.Sign(stringToSign, privateKey); Console.WriteLine(sig); } } public class Security { public static string UrlEncodeTo64(byte[] bytesToEncode) { string returnValue = System.Convert.ToBase64String(bytesToEncode); return HttpUtility.UrlEncode(returnValue); } public static string Sign(string value, string key) { using (var hmac = new HMACSHA1(Encoding.ASCII.GetBytes(key))) { return UrlEncodeTo64(hmac.ComputeHash(Encoding.ASCII.GetBytes(value))); } } public static int UtcTimestamp( TimeSpan timeSpanToAdd) { TimeSpan ts = (DateTime.UtcNow.Add(timeSpanToAdd) - new DateTime(1970,1,1,0,0,0)); int expires_int = (int) ts.TotalSeconds; return expires_int; } } } back to index

API URL Generator and API URL Tester

The safest way to authenticate is using one of the code examples above to build a dynamic signature that expires shortly after the request is executed (1 minute expire time is recommended). If that is not an option for you, you can navigate to Tools / API URL Generator and generate a signature that is valid for the selected amount of time: Available expire times: 1 minute, hour, day, week, month, year, 5 years, 10 years, 100 years. Please be aware that generating a API signature that is valid for a longer time may decrease the overall API security as someone getting to know this signature could perform any API actions! Within the tools section you also find an API URL tester which allows you to check the validity of your signature: back to index

Available request methods

• GET
• POST

back to index

Available action parameters

• view
• add
• update (pro version only)
• delete (pro version only)
• search (pro version only)

back to index

Available type parameters

• marker
• layer

back to index

Global parameters (for all API actions)

Available parameters for type marker

Available parameters for type layer

Special parameters for search action

Additional security options

The MapsMarker API was designed with a focus on security. Besides the basic protection by using public and private key as well as expiration for authentication, you can optionally harden your API settings within the settings panel at Settings / Misc / MapsMarker API:

• API status: allows you to enable or disable the API globally. Default: disabled.
• Allowed API actions: only allow use of the API actions you need. Update, delete and search actions are only available in the pro version
• IP access restriction: only allow access to the API for a defined IP address or IP range
• Allowed referer: additional layer of protection – allow only a specific referer (note: if set, get-requests are not allowed anymore!)
• Allowed API request methods: optionally only allow the method you need

back to index

Response

The response body will be a JSON (default) or XML object containing a success status and the result of the request. The HTTP status code in the header will always be 200 regardless of the result so it’s important to check for the success in the response body to determine the success or failure of the request. So, for example if a non-existent marker is requested the raw response body would be the following: A successful request for a form would look like this: If you are performing an search action, the results are getting returned as child elements within the data-attribute: If you need to extract a JSONP resultset with PHP, you can use the following function for that: function jsonp_decode($jsonp, $assoc = false) { if($jsonp[0] !== '[' && $jsonp[0] !== '{') { $jsonp = substr($jsonp, strpos($jsonp, '(')); } return json_decode(trim($jsonp,'();'), $assoc); } usage: $data = jsonp_decode($resultset); back to index

Examples

Below you will find some example showing how the API can be used. If you have any questions, please open a support ticket!

GET-Requests

• View marker with ID2: https://your-domain/wp-content/plugins/leaflet-maps-marker-pro/leaflet-api.php?key=YOUR_PUBLIC_KEY&signature=YOUR_SIGNATURE&expires=YOUR_EXPIRE_VALUE&action=view&type=marker&id=2
• View layer with ID 3 in XML-output: https://your-domain/wp-content/plugins/leaflet-maps-marker-pro/leaflet-api.php?key=YOUR_PUBLIC_KEY&signature=YOUR_SIGNATURE&expires=YOUR_EXPIRE_VALUE&action=view&type=layer&id=2&format=xml
• Add new marker, title Headquarter, geocode Main Street 1 Washington: https://your-domain/wp-content/plugins/leaflet-maps-marker-pro/leaflet-api.php?key=YOUR_PUBLIC_KEY&signature=YOUR_SIGNATURE&expires=YOUR_EXPIRE_VALUE&action=add&type=marker&markername=Headquarter&geocode=Main Street 1 Washington
• Add new layer, title Stores, directly add lat/lon and address: https://your-domain/wp-content/plugins/leaflet-maps-marker-pro/leaflet-api.php?key=YOUR_PUBLIC_KEY&signature=YOUR_SIGNATURE&expires=YOUR_EXPIRE_VALUE&action=add&type=layer&name=Store&lat=48.3434&lon=16.43234&address=Store Adress Washington
• Update marker with ID2, set popuptext to “new popuptext” (pro version only): https://your-domain/wp-content/plugins/leaflet-maps-marker-pro/leaflet-api.php?key=YOUR_PUBLIC_KEY&signature=YOUR_SIGNATURE&expires=YOUR_EXPIRE_VALUE&action=update&type=marker&id=2&popuptext=new popuptext
• Update layer with ID 3, hide list of markers below map (pro version only): https://your-domain/wp-content/plugins/leaflet-maps-marker-pro/leaflet-api.php?key=YOUR_PUBLIC_KEY&signature=YOUR_SIGNATURE&expires=YOUR_EXPIRE_VALUE&action=update&type=layer&id=3&listmarkers=0
• Delete marker with ID2 (pro version only): https://your-domain/wp-content/plugins/leaflet-maps-marker-pro/leaflet-api.php?key=YOUR_PUBLIC_KEY&signature=YOUR_SIGNATURE&expires=YOUR_EXPIRE_VALUE&action=delete&type=marker&id=
• Delete layer with ID3 (->delete layer only; pro version only): https://your-domain/wp-content/plugins/leaflet-maps-marker-pro/leaflet-api.php?key=YOUR_PUBLIC_KEY&signature=YOUR_SIGNATURE&expires=YOUR_EXPIRE_VALUE&action=delete&type=layer&id=3
• Delete layer with ID3 (-> delete layer and assigned markers; pro-version only): https://your-domain/wp-content/plugins/leaflet-maps-marker-pro/leaflet-api.php?key=YOUR_PUBLIC_KEY&signature=YOUR_SIGNATURE&expires=YOUR_EXPIRE_VALUE&action=delete&type=layer&id=3&delete_markers=true
• Search all markers which are assigned to layer ID 7 (pro version only): https://your-domain/wp-content/plugins/leaflet-maps-marker-pro/leaflet-api.php?key=YOUR_PUBLIC_KEY&signature=YOUR_SIGNATURE&expires=YOUR_EXPIRE_VALUE&action=search&type=marker&searchkey=layer&searchvalue=7
• Search all layers with name = test (pro version only): https://your-domain/wp-content/plugins/leaflet-maps-marker-pro/leaflet-api.php?key=YOUR_PUBLIC_KEY&signature=YOUR_SIGNATURE&expires=YOUR_EXPIRE_VALUE&action=search&type=layer&searchkey=name&searchvalue=test
• Search all markers which were created after 2013-10-01 12:00:00 and before 2014-01-01 12:00:00 (pro version only): https://your-domain/wp-content/plugins/leaflet-maps-marker-pro/leaflet-api.php?key=YOUR_PUBLIC_KEY&signature=YOUR_SIGNATURE&expires=YOUR_EXPIRE_VALUE&action=search&type=marker&searchkey=createdon&date_from=2013-10-01 12:00:00&date_to=2014-01-01 12:00:00
• Search all markers within a bounding box (pro version only): https://your-domain/wp-content/plugins/leaflet-maps-marker-pro/leaflet-api.php?key=YOUR_PUBLIC_KEY&signature=YOUR_SIGNATURE&expires=YOUR_EXPIRE_VALUE&action=search&type=marker&searchkey=boundingbox&lat_top_left=48.283543&lon_top_left=16.228180&lat_bottom_right=48.081642&lon_bottom_right=16.640854

back to index

POST-Requests:

You can also use POST-request to call the Maps Marker API – whereas you can use the same parameters as in the GET-request-examples above. These parameters can be added to a html form for example: View marker with ID1: <form action="https://your-domain/wp-content/plugins/leaflet-maps-marker-pro/leaflet-api.php" method="POST"> <input type="hidden" name="key" value="YOUR_PUBLIC_KEY"/> <input type="hidden" name="signature" value="YOUR_SIGNATURE"/> <input type="hidden" name="expires" value="YOUR_EXPIRE_VALUE"/> <input type="text" name="action" value="view"/> <input type="text" name="type" value="marker"/> <input type="text" name="id" value="1"/> <input type="submit" name="submit" value="submit"/> </form> Add new marker, title Headquarter, geocode Main Street 1 Washington: <form action="https://your-domain/wp-content/plugins/leaflet-maps-marker-pro/leaflet-api.php" method="POST"> <input type="hidden" name="key" value="YOUR_PUBLIC_KEY"/> <input type="hidden" name="signature" value="YOUR_SIGNATURE"/> <input type="hidden" name="expires" value="YOUR_EXPIRE_VALUE"/> <input type="text" name="action" value="add"/> <input type="text" name="type" value="marker"/> <input type="text" name="markername" value="Headquarters"/> <input type="text" name="geocode" value="Main Street 1 Washington"/> <input type="submit" name="submit" value="submit"/> </form> Update marker with ID2, set popuptext to “new popuptext” (pro version only): <form action="https://your-domain/wp-content/plugins/leaflet-maps-marker-pro/leaflet-api.php" method="POST"> <input type="hidden" name="key" value="YOUR_PUBLIC_KEY"/> <input type="hidden" name="signature" value="YOUR_SIGNATURE"/> <input type="hidden" name="expires" value="YOUR_EXPIRE_VALUE"/> <input type="text" name="action" value="update"/> <input type="text" name="type" value="marker"/> <input type="text" name="id" value="2"/> <input type="text" name="popuptext" value="new popuptext"/> <input type="submit" name="submit" value="submit"/> </form> Search all markers which are assigned to layer ID 7 (pro version only): <form action="https://your-domain/wp-content/plugins/leaflet-maps-marker-pro/leaflet-api.php" method="POST"> <input type="hidden" name="key" value="YOUR_PUBLIC_KEY"/> <input type="hidden" name="signature" value="YOUR_SIGNATURE"/> <input type="hidden" name="expires" value="YOUR_EXPIRE_VALUE"/> <input type="text" name="action" value="search"/> <input type="text" name="type" value="marker"/> <input type="text" name="searchkey" value="layer"/> <input type="text" name="searchvalue" value="7"/> <input type="submit" name="submit" value="submit"/> </form> back to index