Reverse Geocoding
If you need to find out what address, city, or region are at a set of coordinates, then you need Reverse Geocoding.
For the opposite, see Forward Geocoding.
Storing and Limits
Temporary Geocoding Only
Server side storage and/or caching of responses is currently not permitted due to licensing.
All requests should be in response to end user actions.
Service Limits
Free Plan accounts are limited to a total of 60 requests per minute. Limit hits can be tracked in Per Key analytics, and will show as a 1-min rate limit of "search". Blocked requests will return a 429 response code, and a "reject-reason" header of "Account Maximum Reached".
Request
Make the HTTPS Get or Post request using the url and parameters below.
We recommend GET whenever possible for browser and CDN caching.
Get URL
Post URL
Parameter | Description |
---|---|
key String Required |
The API Key created on your Account page after you login to Slpy. |
lat Number Required |
The latitude of the location being requested. |
lon Number Required |
The longitude of the location being requested. |
level Integer optional |
Desired location type by Level number between 1-10. Default: 10
|
polygon String optional |
Desired polygon format of geojson, kml, svg, or text. Returns a polygon and boundingbox of the result, or point if none available. Results for large detailed features can result in slower performance. Default: No polygon returned.
|
language String optional |
The preferred two character language code for the returned result. See Supported Languages for a list of codes available. Default is "en" for English. |
country String optional |
The two character iso_alpha2 country code. Default: deternmines country from coordinates. |
Example
Request usage
Get URL
Post URL
Post Data Object | Value |
---|---|
level | 10 |
lat | 47.6205 |
lon | -122.3493 |
polygon | geojson |
language | en |
Response
The response is returned as a JSON formatted object, which contains information on the location as well as how confident it was in the result and how accurate the geocoordinates are.
Example Response
Level
A location level scale from 0-10, with 10 being an exact street address match, and 1 being a country match.
Important: Geocoding will always try to return the next best level, rather than no result. For example, a request for a street that can't be found may return the city, region, or country. This behaviour allows you to decide what level range is acceptable for your use case, instead of simply success or failure.
Parameter | Description |
---|---|
10 | Exact match on street address, often with roof level accuracy |
9 | Matched street address with approximate accuracy |
8 | A street address calculated from surrounding street numbers on the same road |
7 | Road level accuracy or unvalidated street location |
6 | Suburb or neighborhood center |
5 | Postalcode center |
4 | City or Town centroid |
3 | District or County center |
2 | Region or State center |
1 | Country center |
0 | None or no results |
Details
Parameter | Description |
---|---|
accuracy | A string denoting extra information on the level of location found. |
lat | The latitude of the returned point |
lon | The longitude of the returned poin |
status |
|
distance | Distance between the requested coordinates and the returned result in KM. |
polygon | optional - When a polygon format is requested, this will contain a Polygon or Point in that format. |
boundingbox | optional - When a polygon format is requested AND a polygon is returned, this will conatin a maximum/minimum latitude and longitude array. |
license | Required attribution, copyrights, and legal disclaimer. "© Slpy, © OpenStreetMap contributors" should be displayed on the map or somewhere near the results displayed information as required by our partners and data sources. |
Properties
An object containing additional Properties of the returned response.
Parameter | Description |
---|---|
name | optional - POI name if available |
street | optional - Road number, or location name, with street name in country native format. |
neighborhood | optional - From Suburb or Neighborhood down to Retail or Residential level area. |
sub_city | optional - When location has Town, Village, Hamlet, or Borough level, AND is also part of a larger City area. |
city | optional - Independent City or Town area. |
postcode | optional - Postal code or Zipcode. |
district | optional - District or county level. |
district_short | optional - Abbreviation of District or county level. |
region | optional - State or region level. |
region_short | optional - Abbreviation of State or region level. |
country_code | optional - two character iso_alpha2 country code. |
country | optional - Long name of country. |
address | optional - Full postal address formatted in the country's native format. Will try to return mailing address if street or name are available, or a well formatted reference area if not. |
Code Examples
Simple GET requests to the Structured search in different programming languages.
import requests
api_url = 'https://api.slpy.com/v1/search'
params = {
'lat': 'example_lat',
'lon': 'example_lon',
'level': '10',
'polygon': 'geojson',
'country': 'example_country',
'key': 'your_api_key'
}
response = requests.get(api_url, params=params)
if response.status_code == 200:
print(response.json())
else:
print('Error:', response.status_code)
function fetchData(params) {
const apiUrl = 'https://api.slpy.com/v1/search';
fetch(`${apiUrl}?${params}`)
.then(response => {
if (response.ok) {
return response.json();
} else {
throw new Error(`Error: ${response.status}`);
}
})
.then(data => {
console.log(data);
})
.catch(error => {
console.error(error);
});
}
const params = new URLSearchParams({
lat: 'example_lat',
lon: 'example_lon',
level: '10',
polygon: 'geojson',
country: 'example_country',
key: 'your_api_key'
});
fetchData(params);
require 'net/http'
require 'uri'
require 'json'
api_url = 'https://api.slpy.com/v1/search'
params = {
'lat' => 'example_lat',
'lon' => 'example_lon',
'level' => '10',
'polygon' => 'geojson',
'country' => 'example_country',
'key' => 'your_api_key'
}
uri = URI.parse(api_url)
uri.query = URI.encode_www_form(params)
response = Net::HTTP.get_response(uri)
if response.code == '200'
data = JSON.parse(response.body)
puts data
else
puts "Error: #{response.code}"
end
<?php
$apiUrl = 'https://api.slpy.com/v1/search';
$params = array(
'lat' => 'example_lat',
'lon' => 'example_lon',
'level' => '10',
'polygon' => 'geojson',
'country' => 'example_country',
'key' => 'your_api_key'
);
$query = http_build_query($params);
$url = $apiUrl . '?' . $query;
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
if (curl_errno($ch)) {
echo 'Error:' . curl_error($ch);
} else {
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($statusCode == 200) {
$data = json_decode($response);
print_r($data);
} else {
echo 'Error: ' . $statusCode;
}
}
curl_close($ch);
?>
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
public class ApiExample {
public static void main(String[] args) {
String apiUrl = "https://api.slpy.com/v1/search";
String params = "lat=example_lat&lon=example_lon&level=10&polygon=geojson&country=example_country&key=your_api_key";
String url = apiUrl + "?" + params;
try {
URL obj = new URL(url);
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
if (responseCode == HttpURLConnection.HTTP_OK) {
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
} else {
System.out.println("Error: " + responseCode);
}
} catch (IOException e) {
e.printStackTrace();
}
}
}
package main
import (
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
"net/url"
)
func main() {
apiUrl := "https://api.slpy.com/v1/search"
params := url.Values{}
params.Set("lat", "example_lat")
params.Set("lon", "example_lon")
params.Set("level", "10")
params.Set("polygon", "geojson")
params.Set("country", "example_country")
params.Set("key", "your_api_key")
resp, err := http.Get(fmt.Sprintf("%s?%s", apiUrl, params.Encode()))
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
defer resp.Body.Close()
if resp.StatusCode == http.StatusOK {
bodyBytes, err := ioutil.ReadAll(resp.Body)
if err {
fmt.Printf("Error reading response body: %v\n", err)
return
}
var data interface{}
json.Unmarshal(bodyBytes, &data)
fmt.Println(data)
} else {
fmt.Printf("Error: %d\n", resp.StatusCode)
}
}
Demo Examples
Real world examples and common use cases.
Map Demo
- Click on place names, streets, and buildings to return the nearest result based on the assumed location level.
Next Steps
Enhance your search with Maps or Autocomplete
Forward Geocoding
- Get the location of an address
- Search for points of interest
- Add a search bar to your map
Autocomplete
- Enhance your input
- Rapid search cities or regions
- Guide your search
Maps
- Display your location
- Provide context to an address
- Add popups for more information