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)

Parameter	Required?	Data type	Default value	Notes
version	optional	integer	1
key	required	string		Public API key, has to be set via Settings / Misc / MapsMarker API
signature	required	string		see chapter about authentication for more details
expires	required	string		see chapter about authentication for more details
format	optional	string	json	json or xml - default can be set via Settings / MapsMarker API
remap_*	optional	string	NULL	allows to remap output of field IDs (e.g. remap_lon=longitude) -> < longitude >...< /longitude >
callback	optional	string	jsonp	JSONP callback function name - default can be set via Settings / MapsMarker API

back to index

Available parameters for type marker

Parameter	Required?	Datatype	Default value	Supported in actions	Notes
id	required	integer	set automatically when adding a new marker	view add update delete search
markername	optional	string	NULL	view add update search
geocode	optional	string	NULL	add update	value gets geoencoded via Google Places API and overwrites parameter lat, lon and address
basemap	optional	predefined basemap IDs - see notes	default 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
layer	optional	integer	default layer for new marker (see settings)	view add update search
lat	optional	float	default location for new marker (see settings)	view add update search	gets overwritten if parameter geocode is used!
lon	optional	float	default location for new marker (see settings)	view add update search	gets overwritten if parameter geocode is used!
icon	optional	string (e.g. bus.png)	NULL	view 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.
popuptext	optional	string	NULL	view add update search
zoom	optional	integer	default zoom for new marker (see settings)	view add update search
openpopup	optional	boolean	default value for new markers (see settings)	view add update search
mapwidth	optional	integer	default mapwidth for new markers (see settings)	view add update search
mapwidthunit	optional	string	default value for new markers (see settings)	view add update search
mapheight	optional	integer	default mapheight for new markers (see settings)	view add update search
panel	optional	boolean	default value for new markers (see settings)	view add update search
createdby	optional	string	NULL	view add update search
createdon	optional	date (Y-m-d H:i:s)	NULL	view add update search
updatedby	optional	string	NULL	view add update search
updatedon	optional	date (Y-m-d H:i:s)	date('Y-m-d H:i:s)	view add update search
controlbox	optional	integer	default value for new markers (see settings)	view add update search	possible values: 0,1,2
overlays_custom	optional	boolean	default value for new markers (see settings)	view add update search
overlays_custom2	optional	boolean	default value for new markers (see settings)	view add update search
overlays_custom3	optional	boolean	default value for new markers (see settings)	view add update search
overlays_custom4	optional	boolean	default value for new markers (see settings)	view add update search
wms	optional	boolean	default value for new markers (see settings)	view add update search
wms2	optional	boolean	default value for new markers (see settings)	view add update search
wms3	optional	boolean	default value for new markers (see settings)	view add update search
wms4	optional	boolean	default value for new markers (see settings)	view add update search
wms5	optional	boolean	default value for new markers (see settings)	view add update search
wms6	optional	boolean	default value for new markers (see settings)	view add update search
wms7	optional	boolean	default value for new markers (see settings)	view add update search
wms8	optional	boolean	default value for new markers (see settings)	view add update search
wms9	optional	boolean	default value for new markers (see settings)	view add update search
wms10	optional	boolean	default value for new markers (see settings)	view add update search
kml_timestamp	optional	date (Y-m-d H:i:s)	NULL	view add update search
address	optional	string	NULL	view add update search	gets overwritten if parameter geocode is used!
gpx_url	optional	string	NULL	view add update search	since v1.2p
gpx_panel	optional	boolean	0	view add update search	since v1.2p

back to index

Available parameters for type layer

Parameter	Required?	Datatype	Default value	Supported in actions	Notes
id	required	integer	set automatically when adding a new marker	view add update delete search
geocode	optional	string	NULL	add update	value gets geoencoded via Google Places API and overwrites parameter lat, lon and address
name	optional	string	NULL	view add update search
basemap	optional	predefined values	default 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
layerzoom	optional	integer	default zoom for new layer (see settings)	view add update search
mapwidthunit	optional	string	default value for new layer (see settings)	view add update search
mapwidth	optional	integer	default mapwidth for new layer (see settings)	view add update search
mapheight	optional	integer	default mapheight for new layer (see settings)	view add update search
panel	optional	boolean	default value for new layer (see settings)	view add update search
layerviewlat	optional	float	default lat for new layer (see settings)	view add update search	gets overwritten if parameter geocode is used!
layerviewlon	optional	float	default lon for new layer (see settings)	view add update search	gets overwritten if parameter geocode is used!
createdby	optional	string	NULL	view add update search
createdon	optional	date (Y-m-d H:i:s)	NULL	view add update search
updatedby	optional	string	NULL	view add update search
updatedon	optional	date (Y-m-d H:i:s)	date('Y-m-d H:i:s)	view add update search
controlbox	optional	integer	default value for new layer (see settings)	view add update search	possible values: 0, 1, 2
overlays_custom	optional	boolean	default value for new layer (see settings)	view add update search
overlays_custom2	optional	boolean	default value for new layer (see settings)	view add update search
overlays_custom3	optional	boolean	default value for new layer (see settings)	view add update search
overlays_custom4	optional	boolean	default value for new layer (see settings)	view add update search
wms	optional	boolean	default value for new layer (see settings)	view add update search
wms2	optional	boolean	default value for new layer (see settings)	view add update search
wms3	optional	boolean	default value for new layer (see settings)	view add update search
wms4	optional	boolean	default value for new layer (see settings)	view add update search
wms5	optional	boolean	default value for new layer (see settings)	view add update search
wms6	optional	boolean	default value for new layer (see settings)	view add update search
wms7	optional	boolean	default value for new layer (see settings)	view add update search
wms8	optional	boolean	default value for new layer (see settings)	view add update search
wms9	optional	boolean	default value for new layer (see settings)	view add update search
wms10	optional	boolean	default value for new layer (see settings)	view add update search
listmarkers	optional	boolean	default value for new layer (see settings)	view add update search	option to show list of markers below layer maps
multi_layer_map	optional	boolean	0	view add update search
multi_layer_map_list	optional	string (comma-separated layer-IDs or all)	NULL	view add update search	e.g. 1,2,3,4 or all
address	optional	string	NULL	view add update search	gets overwritten if parameter geocode is used!
delete_markers	optional	true/false	false	delete	when used on delete action, also assigned markers are deleted
clustering	optional	boolean	default value for new layer (see settings)	view add update search	available in pro version only
gpx_url	optional	string	NULL	view add update search	since v1.2p
gpx_panel	optional	boolean	0	view add update search	since v1.2p
mlm_filter	optional	integer	default value for new layer (see settings)	view add update
mlm_filter_details	optional	JSON string	NULL	view add update

back to index

Special parameters for search action

Parameter	Required?	Data type	Notes
searchkey	required	string	Allowed 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
searchvalue	depends	string or integer	generally required but optional when using searchkey createdon, updatedon or boundingbox
date_from	depends	string (Y-m-d H:i:s)	generally optional but required when using searchkey createdon or updatedon
date_to	depends	string (Y-m-d H:i:s)	generally optional but required when using searchkey createdon or updatedon
lat_top_left	depends	floatval(6)	generally optional but required when using searchkey boundingbox
lon_top_left	depends	floatval(6)	generally optional but required when using searchkey boundingbox
lat_bottom_right	depends	floatval(6)	generally optional but required when using searchkey boundingbox
lon_bottom_right	depends	floatval(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 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