Everything you need to know to start using the Wikiocity API
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.
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.
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.
https://api.wikiocity.com/r/search?street={street}&city={city}&state={state}&zipcode={zipcode}&key={your_api_key}
https://api.wikiocity.com/r/search?search={search string}&key={your_api_key}
https://api.wikiocity.com/r/search?key={your_api_key}
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"}
Here are some examples to help you get started.
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/latest/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">
<!-- MglJS -->
<script src="https://api.wikiocity.com/lib/mlgl/latest/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>
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/latest/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">
<!-- MglJS -->
<script src="https://api.wikiocity.com/lib/mlgl/latest/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>