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.
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
GET - General URL
POST - Structured and General URL
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.
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.
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.
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.
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.