Everything you need to know to start using the Wikiocity API
Everything needed to get scalable interactive maps running on your site.
Go over the list of javascript variables below to modify how maps function and load. Pay attention to variable order and whether the variable is local or global as denoted by the use of var
//settings
var apiKey = 'your_api_key';
var targetDivId = 'map';
var mapType = 'vector';
mapLanguage = 'en';
MglOptions = { mapStyle: 'default', navControl: 'top-left', hash: true};
OpenLayersFallback = true;
ieRasterFallback = true;
setInteractionOnFocus(targetDivId);
var latitude = '0.0';
var longitude = '-0.0';
var startZoom = '3';
Modern mapping software is often not compatible with older browsers without modification. Because this represents a significant amount of traffic for large websites, we made it easy to allow fallback to other map software and have kept our own libraries cross platform compatible.
Polyfills enables backwards compatibility for features not found in older browsers. Inlcude the below lines in your <head>
, and before any other script includes. Best used in combination with OpenLayersFallback and ieRasterFallback set to true to enable support for older Internet Explorer versions, and IE 11/Edge browsers that are not recently updated.
NOTICE: Please note when setting ieRasterFallback to true that Raster maps incur higher costs than Vector. Average traffic fallback is 1%. Polyfills are still recommended regardless of ieRasterFallback setting.
<!-- The polyfills below are only needed for old environments like Internet Explorer and Android 4.x -->
<script src="https://api.wikiocity.com/lib/wm/latest/wikiocity-polyfill.js"></script>
MapLibre-GL uses WebGL to display smooth and beautiful maps, but WebGL is not supported by older browsers. Internet Explorer 9 and 10, as well as IE11 and Edge when not updated, do not support WebGL.
To make this work, we test for successful MapLibre-GL loading, and whether WebGl is functional and will perform acceptably. A positive test will return true for MglReady. If WebGL fails, we load the libraries for OpenLayers by inserting them in to the DOM Head, and run OnOLReady() when done. While most code will be a simple copy/paste between the "MapLibre-GL Compatible code" and "OL Compatible Code", the two are seperated for easy use of library specific code. Modify your map with the code below to get started.
//settings
OpenLayersFallback = true;
ieRasterFallback = true;
//map code
var center = [longitude,latitude];
var map = MglMap(apiKey, targetDivId, center, startZoom, mapType);
//code for markers, options, or other functions.
if (MglReady) {
//MapLibre-GL Compatible code
} else {
function OnOLReady() {
//OL Compatible Code
}
}
NOTICE: Vector maps only. Not currently supported on Raster. Let us know in the forums if you need this feature.
Use the global mapFilter array variable to remove features and content from vector maps, and filter out things like points of interest.
//settings
mapFilter = ['mid_points', 'other_points'];
Go over the list of javascript variables below to modify how maps function and load. Pay attention to variable order and whether the variable is local or global as denoted by the use of var
//settings
var apiKey = 'your_api_key';
var targetDivId = 'map';
var mapType = 'vector';
mapLanguage = 'en';
ieRasterFallback = true;
setInteractionOnFocus(targetDivId);
var latitude = '0.0';
var longitude = '-0.0';
var startZoom = '3';
Modern mapping software is often not compatible with older browsers without modification. Because this represents a significant amount of traffic for large websites, we made it easy to allow fallback to other map software and have kept our own libraries cross platform compatible.
Polyfills enables backwards compatibility for features not found in older browsers. Inlcude the below lines in your <head>
, and before any other script includes. Best used in combination with ieRasterFallback set to true to enable support for older Internet Explorer versions, and IE 11/Edge browsers that are not recently updated.
NOTICE: Please note when setting ieRasterFallback to true that Raster maps incur higher costs than Vector. Average traffic fallback is 1%. Polyfills are still recommended regardless of ieRasterFallback setting.
<!-- The polyfills below are only needed for old environments like Internet Explorer and Android 4.x -->
<script src="https://api.wikiocity.com/lib/wm/latest/wikiocity-polyfill.js"></script>
NOTICE: Vector maps only. Not currently supported on Raster. Let us know in the forums if you need this feature.
Use the global mapFilter array variable to remove features and content from vector maps, and filter out things like points of interest.
//settings
mapFilter = ['mid_points', 'other_points'];
NOTICE: Aerial and City Level is currently United Sates only.
You can add Aerial Imagery with a single line of code using the Wikiocity-Maps library, and it will automatically play nicely with styles and street level view. The icon will dissapear when zooming in too close or over an area where imagery is not available.
//after map code
addAerialImagery();
https://api.wikiocity.com/r/app/{*aerial-type}/{z}/{x}/{y}.png?key={your_api_key}
The Wikiocity-Maps library easily adds Mapillary's Street Level view to our maps, and it will automatically play nicely with styles and Aerial Imagery. First get your Mapillary Token by signing up at Mapillary.com. Then add it to you map with a single line of code and some styling!
Copy-paste the javascript <script>
and CSS lines below into your <head>
or into the <body>
between the map software and wikiocity-maps.js library.
<style>
.map, #map-mapillary {
width: 100%;
height:400px;
}
.map {float:right}
#mly {
width: 65%;
height: 100%;
float: left;
border-top-right-radius: 8px;
border-bottom-right-radius: 8px;
box-shadow: 5px 0px 3px rgba(0, 0, 0, 0.08);
z-index: 3;
display: none;
}
#mly:after {
font-family: Arial,Helvetica,sans-serif;
content: "Finding Street Level Photos...";
position: absolute;
color: white;
top: 50%;
width: 100%;
text-align: center;
z-index: -1;
}
</style>
<div id="map-mapillary"><div id="map" class="map"></div><div id="mly"></div></div>
//after map code
addMapillary('Your Mapillary Token');
While our standard maps include the most used features, there will always be additional data that people need for different use cases.
A popular example would be county lines and labels for the United States. To achieve this, we can add an additional layer over our map that includes all the needed geometry and names. TopoJSON is a great and compact format for this, but most mapping programs support many other formats like GeoJSON, XML, and more.
//after map code
function countyStyle(feature, resolution) {
return new ol.style.Style({
stroke: new ol.style.Stroke({
color: '#319FD3',
width: 0.5,
}),
text: new ol.style.Text({
text: feature.get('name'),
fill: new ol.style.Fill({color: '#319FD3'}),
})
});
}
var vectorCounties = new ol.layer.Vector({
source: new ol.source.Vector({
//Data from https://github.com/topojson/us-atlas
url: 'https://api.wikiocity.com/data/counties-10m.json',
format: new ol.format.TopoJSON({
layers: ['counties'],
}),
overlaps: false,
}),
style: countyStyle,
});
map.addLayer(vectorCounties);
Here are other examples of how it can be done in Leaflet (TopoJSON Leaflet Example), and MapLibre-GL as well (TopoJSON MapLibre GL Example).