Important notice: the WebAPI has been removed with Maps Marker Pro v4.0.
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
- 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
- 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!
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
Available action parameters
- view
- add
- update (pro version only)
- delete (pro version only)
- search (pro version only)
Available type parameters
- marker
- layer
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 |
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 |
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 |
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 |
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
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
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
Comments or further questions?
If you're looking for technical support please click here, for all other questions please use our contact form to get in touch! We´re looking forward to hearing from you!
Your Maps Marker Pro team