Web API

ATTENTION: these API docs are valid for pro v1.5.7 or higher and free v3.8.6 or higher only – if you are using an older version, please update to the latest version as the old authentication method is not supported anymore! 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

  • 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: api-set-enabled As next step you have to set a public and private API key: public-private-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: api-url-generator 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: api-url-tester 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)

ParameterRequired?Data typeDefault valueNotes
versionoptionalinteger1
keyrequiredstringPublic API key, has to be set via Settings / Misc / MapsMarker API
signaturerequiredstringsee chapter about authentication for more details
expiresrequiredstringsee chapter about authentication for more details
formatoptionalstringjsonjson or xml - default can be set via Settings / MapsMarker API
remap_*optionalstringNULLallows to remap output of field IDs (e.g. remap_lon=longitude) -> < longitude >...< /longitude >
callbackoptionalstringjsonpJSONP callback function name - default can be set via Settings / MapsMarker API
back to index

Available parameters for type marker

ParameterRequired?DatatypeDefault valueSupported in actionsNotes
idrequiredintegerset automatically when adding a new markerview
add
update
delete
search
markernameoptionalstringNULLview
add
update
search
geocodeoptionalstringNULLadd
update
value gets geoencoded via Google Places API and overwrites parameter lat, lon and address
basemapoptionalpredefined basemap IDs - see notesdefault basemap for new marker (see settings)view
add
update
search
osm_mapnik, mapquest_osm, mapquest_aerial, googleLayer_roadmap, googleLayer_satellite, googleLayer_hybrid, googleLayer_terrain, bingaerial, bingaerialwithlabels, bingroad, ogdwien_basemap, ogdwien_satellite, mapbox, mapbox2, mapbox3, custom_basemap, custom_basemap2, custom_basemap3, empty_basemap
layeroptionalintegerdefault layer for new marker (see settings)view
add
update
search
latoptionalfloatdefault location for new marker (see settings)view
add
update
search
gets overwritten if parameter geocode is used!
lonoptionalfloatdefault location for new marker (see settings)view
add
update
search
gets overwritten if parameter geocode is used!
iconoptionalstring (e.g. bus.png)NULLview
add
update
search
if NULL, default icon will be used. Please just use the filename of the icon as stated in the example. All icons available in the icon directory (usually /wp-content/uploads/leaflet-maps-marker-icons if you didnt change it in Settings / map defaults / Default values for marker icons) are available for usage.
popuptextoptionalstringNULLview
add
update
search
zoomoptionalintegerdefault zoom for new marker (see settings)view
add
update
search
openpopupoptionalbooleandefault value for new markers (see settings)view
add
update
search
mapwidthoptionalintegerdefault mapwidth for new markers (see settings)view
add
update
search
mapwidthunitoptionalstringdefault value for new markers (see settings)view
add
update
search
mapheightoptionalintegerdefault mapheight for new markers (see settings)view
add
update
search
paneloptionalbooleandefault value for new markers (see settings)view
add
update
search
createdbyoptionalstringNULLview
add
update
search
createdonoptionaldate (Y-m-d H:i:s)NULLview
add
update
search
updatedbyoptionalstringNULLview
add
update
search
updatedonoptionaldate (Y-m-d H:i:s)date('Y-m-d H:i:s)view
add
update
search
controlboxoptionalintegerdefault value for new markers (see settings)view
add
update
search
possible values: 0,1,2
overlays_customoptionalbooleandefault value for new markers (see settings)view
add
update
search
overlays_custom2optionalbooleandefault value for new markers (see settings)view
add
update
search
overlays_custom3optionalbooleandefault value for new markers (see settings)view
add
update
search
overlays_custom4optionalbooleandefault value for new markers (see settings)view
add
update
search
wmsoptionalbooleandefault value for new markers (see settings)view
add
update
search
wms2optionalbooleandefault value for new markers (see settings)view
add
update
search
wms3optionalbooleandefault value for new markers (see settings)view
add
update
search
wms4optionalbooleandefault value for new markers (see settings)view
add
update
search
wms5optionalbooleandefault value for new markers (see settings)view
add
update
search
wms6optionalbooleandefault value for new markers (see settings)view
add
update
search
wms7optionalbooleandefault value for new markers (see settings)view
add
update
search
wms8optionalbooleandefault value for new markers (see settings)view
add
update
search
wms9optionalbooleandefault value for new markers (see settings)view
add
update
search
wms10optionalbooleandefault value for new markers (see settings)view
add
update
search
kml_timestampoptionaldate (Y-m-d H:i:s)NULLview
add
update
search
addressoptionalstringNULLview
add
update
search
gets overwritten if parameter geocode is used!
gpx_urloptionalstringNULLview
add
update
search
since v1.2p
gpx_paneloptionalboolean0view
add
update
search
since v1.2p
back to index

Available parameters for type layer

ParameterRequired?DatatypeDefault valueSupported
in actions
Notes
idrequiredintegerset automatically when adding a new markerview
add
update
delete
search
geocodeoptionalstringNULLadd
update
value gets geoencoded via Google Places API and overwrites parameter lat, lon and address
nameoptionalstringNULLview
add
update
search
basemapoptionalpredefined valuesdefault basemap for new layer (see settings)view
add
update
search
osm_mapnik, mapquest_osm, mapquest_aerial, googleLayer_roadmap, googleLayer_satellite, googleLayer_hybrid, googleLayer_terrain, bingaerial, bingaerialwithlabels, bingroad, ogdwien_basemap, ogdwien_satellite, mapbox, mapbox2, mapbox3, custom_basemap, custom_basemap2, custom_basemap3, empty_basemap
layerzoomoptionalintegerdefault zoom for new layer (see settings)view
add
update
search
mapwidthunitoptionalstringdefault value for new layer (see settings)view
add
update
search
mapwidthoptionalintegerdefault mapwidth for new layer (see settings)view
add
update
search
mapheightoptionalintegerdefault mapheight for new layer (see settings)view
add
update
search
paneloptionalbooleandefault value for new layer (see settings)view
add
update
search
layerviewlatoptionalfloatdefault lat for new layer (see settings)view
add
update
search
gets overwritten if parameter geocode is used!
layerviewlonoptionalfloatdefault lon for new layer (see settings)view
add
update
search
gets overwritten if parameter geocode is used!
createdbyoptionalstringNULLview
add
update
search
createdonoptionaldate (Y-m-d H:i:s)NULLview
add
update
search
updatedbyoptionalstringNULLview
add
update
search
updatedonoptionaldate (Y-m-d H:i:s)date('Y-m-d H:i:s)view
add
update
search
controlboxoptionalintegerdefault value for new layer (see settings)view
add
update
search
possible values: 0, 1, 2
overlays_customoptionalbooleandefault value for new layer (see settings)view
add
update
search
overlays_custom2optionalbooleandefault value for new layer (see settings)view
add
update
search
overlays_custom3optionalbooleandefault value for new layer (see settings)view
add
update
search
overlays_custom4optionalbooleandefault value for new layer (see settings)view
add
update
search
wmsoptionalbooleandefault value for new layer (see settings)view
add
update
search
wms2optionalbooleandefault value for new layer (see settings)view
add
update
search
wms3optionalbooleandefault value for new layer (see settings)view
add
update
search
wms4optionalbooleandefault value for new layer (see settings)view
add
update
search
wms5optionalbooleandefault value for new layer (see settings)view
add
update
search
wms6optionalbooleandefault value for new layer (see settings)view
add
update
search
wms7optionalbooleandefault value for new layer (see settings)view
add
update
search
wms8optionalbooleandefault value for new layer (see settings)view
add
update
search
wms9optionalbooleandefault value for new layer (see settings)view
add
update
search
wms10optionalbooleandefault value for new layer (see settings)view
add
update
search
listmarkersoptionalbooleandefault value for new layer (see settings)view
add
update
search
option to show list of markers below layer maps
multi_layer_mapoptionalboolean0view
add
update
search
multi_layer_map_listoptionalstring (comma-separated layer-IDs or all)NULLview
add
update
search
e.g. 1,2,3,4 or all
addressoptionalstringNULLview
add
update
search
gets overwritten if parameter geocode is used!
delete_markersoptionaltrue/falsefalsedeletewhen used on delete action, also assigned markers are deleted
clusteringoptionalbooleandefault value for new layer (see settings)view
add
update
search
available in pro version only
gpx_urloptionalstringNULLview
add
update
search
since v1.2p
gpx_paneloptionalboolean0view
add
update
search
since v1.2p
mlm_filteroptionalintegerdefault value for new layer (see settings)view
add
update
mlm_filter_detailsoptionalJSON stringNULLview
add
update
back to index

Special parameters for search action

ParameterRequired?Data typeNotes
searchkeyrequiredstringAllowed searchkeys: id, markername, basemap, layer, lat, lon, icon, popuptext, zoom, openpopup, mapwidth, mapwidthunit, mapheight, panel, createdby, createdon, updatedby, updatedon, controlbox, overlays_custom, overlays_custom2, overlays_custom3, overlays_custom4, wms, wms2, wms3, wms4, wms5, wms6, wms7, wms8, wms9, wms10, kml_timestamp, address, gpx_url, gpx_panel, name, layerzoom, layerviewlat, layerviewlon, listmarkers, multi_layer_map, multi_layer_map_list, clustering, boundingbox
searchvaluedependsstring or integergenerally required but optional when using searchkey createdon, updatedon or boundingbox
date_fromdependsstring (Y-m-d H:i:s)generally optional but required when using searchkey createdon or updatedon
date_todependsstring (Y-m-d H:i:s)generally optional but required when using searchkey createdon or updatedon
lat_top_leftdependsfloatval(6)generally optional but required when using searchkey boundingbox
lon_top_leftdependsfloatval(6)generally optional but required when using searchkey boundingbox
lat_bottom_rightdependsfloatval(6)generally optional but required when using searchkey boundingbox
lon_bottom_rightdependsfloatval(6)generally optional but required when using searchkey boundingbox
back to index

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-security-settings

  • 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: response-marker-not-exists A successful request for a form would look like this: response-marker-exists If you are performing an search action, the results are getting returned as child elements within the data-attribute: response-search-results 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

2 thoughts on “Web API

    • Hi Erik,
      thx for pointing this out – actually this is a regression bug, so I just deployed a hotfix for the current v1.9.1 – just download the current package from https://www.mapsmarker.com/download-pro – unzip the files locally and overwrite the file leaflet-api.php on your webserver. This fix will be included officially in the next release.
      best,
      Robert

Leave a Reply

Your email address will not be published. Required fields are marked *