Wikiocity Documentation

Everything you need to know to start using the Wikiocity API

Geocoding

NOTICE: Only United States is currently supported.

If you need to convert an address or place to a set of coordinates, for either centering a map or placing a marker, then you need Geocoding. Our geocoder can take a wide range of inputs, and return the latitude and longitude location, as well as other helpful details.

Making the Request

GET or POST

First we need to issue a HTTP Request by either GET or POST methods. GET is the same kind of request you make when you enter a URL into your browser. All parameters of your geocode search will be included in the URL to GET. POST on the other hand, stores the parameters in the request body. Which one you need will likely depend on what your use case is, but we recommend GET wherever possible for browser and CDN caching. Be aware, Server side caching is currently not permitted due to licensing issues.

Structured or General

Structuring your search will have a large effect on how accurate your results are. A structured search will split an address into its parts, such as street, city, state, and zip. Sometimes we either don't have seperated data, it isn't reasonable to request the user to split it, or what we're search for doesn't apply. In that case, you want to use a general search, where we will try and decode the meaning on our end by parsing commas and fuzzy search.

GET - Structured URL


   		https://api.wikiocity.com/r/search?street={street}&city={city}&state={state}&zipcode={zipcode}&key={your_api_key}

GET - General URL


   		https://api.wikiocity.com/r/search?search={search string}&key={your_api_key}

POST - Structured and General URL


   		https://api.wikiocity.com/r/search?key={your_api_key}

General:

  • search - URL encoded search string with unstructured data. When commas are included, the parser will try to split based on typical address format of "Street, City, State, Zipcode". The Search field cannot be combined with structured fields.

Structured:

  • street - A street field including house number and any apt or suite information.
  • city - City or Town
  • state - State can be fully spelled out, or you may use two character abbreviation.
  • zipcode - US 5-digit zipcode

Handling the Response

The response is returned as a .json object, which contains information on the location as well as how confident it was in the result and how accurate the geocoordinates are.


   		//response
		{"quality":10,"accuracy":"building-house","lat":"40.859","lon":"-73.648","neighborhood":"Bedford Park","county":"Bronx County"}

Details

  • quality - A scale from 0-10, with 10 being the highest accuracy, and confidence, of data. A lower score does not necessarily represent a poor response, as it is also affected by accuracy and the type of request. For example, a request for zipcode coordinates would have a lower quality score than a request for a specific address.
  • accuracy - A string denoting how accurate to the request a location was able to be found. A street address that is successfully located will return "building-house", but if the street is not found it may return "zipcode" if only the zipcode was located.
  • lat - The latitude of the returned point
  • lon - The longitude of the returned point
  • neighborhood - The locations neighborhood if found.
  • county - The locations county if found.

Examples

Here are some examples to help you get started.

General Search from an Input Bar

You can see an example of this in action on our Map Demo page.

In this example, we take a single user input field, and perform a POST request to obtain the coordinates. Once finished, we add a marker and pan and zoom to the location on the map. Please note the inclusion of the jQuery library for simpler requests, and FontAwesome for the markers icon. For OpenLayers users, check the Basic Vector Map page for changes in the map code.

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
  
  <title>Hello World!</title>
  <!-- Mgl CSS -->
  <link href="https://api.wikiocity.com/lib/mlgl/v1.14.0/maplibre-gl.css" rel="stylesheet">
  <link href="https://api.wikiocity.com/style/wikiocity-style.css" rel="stylesheet">
  <link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.14.0/css/all.min.css" rel="stylesheet">

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

  <!-- MglJS -->
  <script src="https://api.wikiocity.com/lib/mlgl/v1.14.0/maplibre-gl.js"></script>
  <script src="https://api.wikiocity.com/style/wikiocity-maps.js"></script>
  
  <!-- jQuery -->
  <script src="https://code.jquery.com/jquery-3.5.1.min.js"></script>
  
  </head>
<body>
    <style>
    .map {
        width: 100%;
        height:400px;
    }
   </style>
   	<form action="#" method="post" id="form" onsubmit="return false;">
        <input class="form-control" id="search" placeholder="Search" type="text" style="width:auto">
	</form>
   <div id="map" class="map"></div>
   <script type="text/javascript">
   		//settings
		var apiKey = 'your_api_key';
   		var targetDivId = 'map';
   		var mapType = 'vector';
   		
   		var latitude = '0.0'; //latitude of your map center
   		var longitude = '-0.0'; //longitude of your map center
   		var startZoom =  '3';
   		
		//map code
   		var center = [longitude,latitude];
   		var map = MglMap(apiKey, targetDivId, center, startZoom, mapType);
		
		//Send a Geocode POST request on input from the Search Bar, then add marker and fly to.
		$(function() {
            $("#form").submit(function(){
                var search = $("#search").val();
				var markers = [];
				$.ajax({
					type: "POST",
					url: "/r/search?key="+apiKey,
					data: {"search": search},
					cache: true,                       
					success: function(response){
						removeMarker(markers,0);
						var obj = response;
						if (obj.lat != '') {
							removeMarker(markers, 0);
							markers = [{ "name" : "", "data":[obj.lat, obj.lon]}];
							addMarkers(markers, map);
							if (MglReady) {
								flyTo(obj, map);
							} else {
								flyTo(obj, view);
							}
						} else {
							alert("Location not found.  Please check your spelling and try again.");
						}
                    }
                });
                return false;
            });
        });
    </script>
</body>
</html>

Structured Search to Generate Markers.

In this example, we take an array of structured addresses, and perform a GET request on each to obtain their coordinates. Once finished, we run addMarkers to add them to the map. Please note the inclusion of the jQuery library for simpler requests, and FontAwesome for the markers icon. For OpenLayers users, check the Basic Vector Map page for changes in the map code.

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
  
  <title>Hello World!</title>
  <!-- Mgl CSS -->
  <link href="https://api.wikiocity.com/lib/mlgl/v1.14.0/maplibre-gl.css" rel="stylesheet">
  <link href="https://api.wikiocity.com/style/wikiocity-style.css" rel="stylesheet">
  <link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.14.0/css/all.min.css" rel="stylesheet">

  <!-- 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/mdn-polyfills[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>

  <!-- MglJS -->
  <script src="https://api.wikiocity.com/lib/mlgl/v1.14.0/maplibre-gl.js"></script>
  <script src="https://api.wikiocity.com/style/wikiocity-maps.js"></script>
  
  <!-- jQuery -->
  <script src="https://code.jquery.com/jquery-3.5.1.min.js"></script>
  
  </head>
<body>
    <style>
    .map {
        width: 100%;
        height:400px;
    }
   </style>
   	<form action="#" method="post" id="form" onsubmit="return false;">
        <input class="form-control" id="search" placeholder="Search" type="text" style="width:auto">
	</form>
   <div id="map" class="map"></div>
   <script type="text/javascript">
   		//settings
		var apiKey = 'your_api_key';
   		var targetDivId = 'map';
   		var mapType = 'vector';
   		
   		var latitude = '0.0'; //latitude of your map center
   		var longitude = '-0.0'; //longitude of your map center
   		var startZoom =  '3';
   		
		//map code
   		var center = [longitude,latitude];
   		var map = MglMap(apiKey, targetDivId, center, startZoom, mapType);
		
		//Address information
		var Addresses = [
			{ 'street' : '4522 Fredericksburg Rd', 'city' : 'Balcones Heights', 'state' : 'TX', 'zipcode' : '78201' },
			{ 'street' : '746 NW Loop 410', 'city' : 'San Antonio', 'state' : 'TX', 'zipcode' : '78216' },
			{ 'street' : '1223 Austin Hwy', 'city' : 'San Antonio', 'state' : 'TX', 'zipcode' : '78209' }
		];
		var markers = [];
		//Loop through addresses, jquery ajax get each result, and add to markers array.  When complete, we run addMarkers to display them.
		var getGeo = function(index){
			if (Addresses.length == index) {
				addMarkers(markers, map);
				return;
			}
			$.ajax({
				type: "GET",
				url: "/r/search?street="+Addresses[index].street+"&city="+Addresses[index].city+"&state="+Addresses[index].state+"&zipcode="+Addresses[index].zipcode+"&key="+apiKey,
				cache: true,                       
				success: function(response){
					markers.push({ 'name' : index, 'data':[response.lat, response.lon, '<div><p>'+Addresses[index].street+'</p></div>'] } );
				},
				complete: function() {
				  getGeo(++index);
				}
			});
		};
		getGeo(0);
    </script>
</body>
</html>