Wikiocity Documentation

Everything you need to know to start using the Wikiocity API

Vector and Raster Maps

Everything needed to get scalable interactive maps running on your site.

Map Settings - MapLibre-GL-JS

Variable Functionality

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;
		ie9RasterFallback = true;
		setInteractionOnFocus(targetDivId);
   		
   		var latitude = '0.0'; 
   		var longitude = '-0.0'; 
   		var startZoom =  '3';

Details:

  • mapLanguage - This is a two character code that sets the language used on labels and roads for the map accross the planet. The default language is 'en' for English. You can use 'intl' for international labeling that uses the native language of the region being viewed.
    • Available Lanugages:
    • intl - Language is in native language of viewed map area.
    • ar - Arabic العربية
    • bn - Bengali বাংলা
    • de - German Deutsch
    • en - English English
    • es - Spanish Español
    • fr - French Français
    • el - Greek ελληνικά
    • hi - Hindi हिन्दी, हिंदी
    • hu - Hungarian Magyar
    • id - Indonesian Bahasa Indonesia
    • it - Italian Italiano
    • ja - Japanese 日本語 (にほんご)
    • ko - Korean 한국어
    • nl - Dutch, Flemish Nederlands, Vlaams
    • pl - Polish Język Polski, Polszczyzna
    • pt - Portuguese Português
    • ru - Russian русский
    • sv - Swedish Svenska
    • tr - Turkish Türkçe
    • vi - Vietnamese Tiếng Việt
    • zh - Chinese 中文 (Zhōngwén), 汉语, 漢語
  • apiKey - This is the key you created for your site on your account page after you login to Api.Wikiocity.
  • targetDivId - This is the id name you used in your map div. You can change the id, but it should alays have a class of "map".
  • mapType - You can choose between 'vector' or 'raster'.
  • MglOptions - You can use this global object to change the default MapLibre-GL Map options, as well as pass mapStyle for changing 3d building setttings or filtering features.
    • mapStyle - Load different map styles.
      • "default" - 3d buildings with antialiasing turned on. May run poorly on slower hardware due to 3d rendering.
      • "2d" - Flat 2d buildings with antialiasing turned off. Better performance on low end hardware.
    • navControl - Adds zoom and compass controls to the map. Set to "top-left" by default. Use "none" for no controls.
    • List of Map Options
  • OpenLayersFallback - If set to true, OpenLayers will be loaded if MapLibre-GL fails to load or is not compatible with the users browser. See Browser Compatibility for additional usage requirements.
  • ie9RasterFallback - If vector is set in mapType, when ie9RasterFallback is true, map type will change to Raster if Internet Explore 9 is detected AND OpenLayersFallback is set to true. Be aware that Raster maps require more credits than Vector. Default setting is false.
  • setInteractionOnFocus(targetDivId) - Map does not pan or zoom unless clicked first. Good for tight mobile pages where scrolling might be captured by the map.
  • Latitude and Longitude - These make up the coordinates of where you want to center your map on loading. If you don't have the latitude and longitude, check out our Search Api for help with geocoding an address. For centering on multiple locations, check the markers page for averaging functions.
  • startZoom - This is the zoom level, ranging from 0-20. 0 is the whole world, and 20 is house level.

Browser Compatibility

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 and ie9RasterFallback

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 ie9RasterFallback set to true to enable support for Internet Explorer 9-10, and IE 11/Edge browsers that are not recently updated.
NOTICE: Please note when setting ie9RasterFallback to true that Raster maps incur higher costs than Vector. Average traffic fallback is 1%. Polyfills are still recommended regardless of ie9RasterFallback setting.

<!-- The polyfills below are only needed for old environments like Internet Explorer and Android 4.x -->
<script src="https://cdn.jsdelivr.net/combine/npm/[email protected],npm/[email protected],npm/[email protected]/MouseEvent.min.js"></script>
<script src="https://cdn.polyfill.io/v3/polyfill.min.js?features=fetch,blissfuljs,default,es2019,Uint8Array,Element.prototype.classList"></script>

MapLibre-GL Failover

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;
		ie9RasterFallback = 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
	
			}
		}

Filter Map Content

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'];

mapFilter - Filter List

  • other_points - This is all uncategorized points of interest that do not fall into one of the levels below.
  • major_points - label (neighborhoods and large shopping areas or buildings), airport, college, golf, park
  • high_points - aerialway, airfield, attraction, cinema, city, department, ferry, grocery, hospital, museum, park2, station, town, village, zoo
  • mid_points - america-football, bank, building, campsite, dam, embassy, fire-station, fuel, furniture, garden, hardware, library, lodging, medical, parking, parking-garage, pharmacy, place-of-worship, police, post, religious-christian, religious-jewish, religious-muslim, school, theatre, town-hall, water
  • low_points - bicycle, bus, telephone, toilets, information
  • detail_points - atm, drinking_water, shower, monument, viewpoint, subway_entrance

Map Settings - OpenLayers

Variable Functionality

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';
		ie9RasterFallback = true;
		setInteractionOnFocus(targetDivId);
   		
   		var latitude = '0.0'; 
   		var longitude = '-0.0'; 
   		var startZoom =  '3';

Details:

  • mapLanguage - This is a two character code that sets the language used on labels and roads for the map accross the planet. The default language is 'en' for English. You can use 'intl' for international labeling that uses the native language of the region being viewed.
    • Available Lanugages:
    • intl - Language is in native language of viewed map area.
    • ar - Arabic العربية
    • bn - Bengali বাংলা
    • de - German Deutsch
    • en - English English
    • es - Spanish Español
    • fr - French Français
    • el - Greek ελληνικά
    • hi - Hindi हिन्दी, हिंदी
    • hu - Hungarian Magyar
    • id - Indonesian Bahasa Indonesia
    • it - Italian Italiano
    • ja - Japanese 日本語 (にほんご)
    • ko - Korean 한국어
    • nl - Dutch, Flemish Nederlands, Vlaams
    • pl - Polish Język Polski, Polszczyzna
    • pt - Portuguese Português
    • ru - Russian русский
    • sv - Swedish Svenska
    • tr - Turkish Türkçe
    • vi - Vietnamese Tiếng Việt
    • zh - Chinese 中文 (Zhōngwén), 汉语, 漢語
  • apiKey - This is the key you created for your site on your account page after you login to Api.Wikiocity.
  • targetDivId - This is the id name you used in your map div. You can change the id, but it should alays have a class of "map".
  • mapType - You can choose between 'vector' or 'raster'.
  • ie9RasterFallback - If vector is set in mapType, when ie9RasterFallback is true, map type will change to Raster if Internet Explore 9 is detected. Be aware that Raster maps require more credits than Vector. Default setting is false.
  • setInteractionOnFocus(targetDivId) - Map does not pan or zoom unless clicked first. Good for tight mobile pages where scrolling might be captured by the map.
  • Latitude and Longitude - These make up the coordinates of where you want to center your map on loading. If you don't have the latitude and longitude, check out our Search Api for help with geocoding an address. For centering on multiple locations, check the markers page for averaging functions.
  • startZoom - This is the zoom level, ranging from 0-20. 0 is the whole world, and 20 is house level.

Browser Compatibility

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 and ie9RasterFallback

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 ie9RasterFallback set to true to enable support for Internet Explorer 9-10, and IE 11/Edge browsers that are not recently updated.
NOTICE: Please note when setting ie9RasterFallback to true that Raster maps incur higher costs than Vector. Average traffic fallback is 1%. Polyfills are still recommended regardless of ie9RasterFallback setting.

<!-- The polyfills below are only needed for old environments like Internet Explorer and Android 4.x -->
<script src="https://cdn.jsdelivr.net/combine/npm/[email protected],npm/[email protected],npm/[email protected]/MouseEvent.min.js"></script>
<script src="https://cdn.polyfill.io/v3/polyfill.min.js?features=fetch,blissfuljs,default,es2019,Uint8Array,Element.prototype.classList"></script>

Filter Map Content

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'];

mapFilter - Filter List

  • other_points - This is all uncategorized points of interest that do not fall into one of the levels below.
  • major_points - label (neighborhoods and large shopping areas or buildings), airport, college, golf, park
  • high_points - aerialway, airfield, attraction, cinema, city, department, ferry, grocery, hospital, museum, park2, station, town, village, zoo
  • mid_points - america-football, bank, building, campsite, dam, embassy, fire-station, fuel, furniture, garden, hardware, library, lodging, medical, parking, parking-garage, pharmacy, place-of-worship, police, post, religious-christian, religious-jewish, religious-muslim, school, theatre, town-hall, water
  • low_points - bicycle, bus, telephone, toilets, information
  • detail_points - atm, drinking_water, shower, monument, viewpoint, subway_entrance

Satellite and Aerial Imagery

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.

Pricing

  • 1 Additional Credit per Aerial Tile load in addition to active Vector or Raster layers.
  • You must have the Everything Api service enabled on your api key.

JS Code

		//after map code
		
	    addAerialImagery();

Implementing without Wikiocity-maps.js

https://api.wikiocity.com/r/app/{*aerial-type}/{z}/{x}/{y}.png?key={your_api_key}
*Aerial Types
  • aerial-imagery - This is ground image only tiles, and does not include streets, labels, political boundaries, or other features. You can overlay our vector maps as shown in wikiocity-maps.js for a high quality combination.
  • aerial-topo - This has ground image tiles with basic features for those who do not support vector overlays.

Street Level View

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!

Libraries

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.

<!-- Mapillary (between Maps Library and Wikiocity-Maps.js) -->
<script src="https://unpkg.com/[email protected]/dist/mapillary.js"></script>
<link href="https://unpkg.com/[email protected]/dist/mapillary.css" rel="stylesheet">

HTML Changes

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

JS Code

		//after map code
		
	    addMapillary('Your Mapillary Token');

Adding Map Content

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.

County Data Example - OpenLayers


   		//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);

Leaflet and MapLibre-GL

Here are other examples of how it can be done in Leaflet (TopoJSON Leaflet Example), and MapLibre-GL as well (TopoJSON MapLibre GL Example).

Data

You can find more TopoJSON data in this World Wide Collection, or check out the data from the above example in this US-Atlas Collection. Be sure to look for and share other sources in the Community Data Forum.