Search and Geocoding
If you need to convert an address or place to a set of coordinates, then you need Geocoding.
For
the reverse, see Reverse 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".
Structured or General
Structuring your search will have a large effect on how accurate your results are. A Structured search has an address that is already split into its parts, such as street, city, region, and postcode. Sometimes we don't have separated data, it isn't reasonable to request the user to split it, or what we're searching 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.
General Search
Use General Requests for addresses and places that require splitting or parsing.
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. |
query String Required |
URL encoded search string with unstructured data. Commas should be used to divide address parts, and the overal format should match the Country's standard address format. The Search field cannot be combined with structured fields. |
country String Required |
The two character iso_alpha2
country code. Use the word GLOBAL for full text search support. The country name should be at the end of the Search field and separated by a comma. |
Example
Request usage
Get URL
Post URL
Post Data Object | Value |
---|---|
query | 400 Broad St, Seattle, WA |
country | us |
Structured Search
Use Structured Search when your address or place is already split into parts.
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. |
country String Required |
The two character iso_alpha2 country code. |
street String optional |
A street field including house number and any apt or suite information. |
city String optional |
City or Town |
region String optional |
State or Region can be fully spelled out, or you may use abbreviations. |
district String optional |
County or District level area |
postcode String optional |
Postalcode or zipcode |
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. |
Example
Request usage
Get URL
Post URL
Post Data Object | Value |
---|---|
street | 400+Broad+St+Sea |
city | seattle |
region | wa |
country | us |
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 |
|
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 |
---|---|
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.
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({
street: 'example_street',
city: 'example_city',
region: 'example_region',
postcode: 'example_postcode',
country: 'example_country',
key: 'your_api_key'
});
fetchData(params);
import requests
api_url = 'https://api.slpy.com/v1/search'
params = {
'street': 'example_street',
'city': 'example_city',
'region': 'example_region',
'postcode': 'example_postcode',
'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)
require 'net/http'
require 'uri'
require 'json'
api_url = 'https://api.slpy.com/v1/search'
params = {
'street' => 'example_street',
'city' => 'example_city',
'region' => 'example_region',
'postcode' => 'example_postcode',
'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(
'street' => 'example_street',
'city' => 'example_city',
'region' => 'example_region',
'postcode' => 'example_postcode',
'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 = "street=example_street&city=example_city®ion=example_region&postcode=example_postcode&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("street", "example_street")
params.Set("city", "example_city")
params.Set("region", "example_region")
params.Set("postcode", "example_postcode")
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)
}
}
import React from 'react';
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);
});
}
function App() {
const params = new URLSearchParams({
street: 'example_street',
city: 'example_city',
region: 'example_region',
postcode: 'example_postcode',
country: 'example_country',
key: 'your_api_key'
});
React.useEffect(() => {
fetchData(params);
}, []);
return (
<div>
Check your console for the API response.
</div>
);
}
export default App;
}
import { Component, OnInit } from '@angular/core';
@Component({
selector: 'app-root',
template: `Check your console for the API response.`
})
export class AppComponent implements OnInit {
ngOnInit() {
this.fetchData();
}
fetchData() {
const apiUrl = 'https://api.slpy.com/v1/search';
const params = new URLSearchParams({
street: 'example_street',
city: 'example_city',
region: 'example_region',
postcode: 'example_postcode',
country: 'example_country',
key: 'your_api_key'
});
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);
});
}
}
<template>
<div>Check your console for the API response.</div>
</template>
<script>
export default {
created() {
this.fetchData();
},
methods: {
fetchData() {
const apiUrl = 'https://api.slpy.com/v1/search';
const params = new URLSearchParams({
street: 'example_street',
city: 'example_city',
region: 'example_region',
postcode: 'example_postcode',
country: 'example_country',
key: 'your_api_key'
});
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);
});
}
}
}
</script>
<script>
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({
street: 'example_street',
city: 'example_city',
region: 'example_region',
postcode: 'example_postcode',
country: 'example_country',
key: 'your_api_key'
});
fetchData(params);
</script>
<main>
Check your console for the API response.
</main>
const fetchData = (params: URLSearchParams) => {
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({
street: 'example_street',
city: 'example_city',
region: 'example_region',
postcode: 'example_postcode',
country: 'example_country',
key: 'your_api_key'
});
fetchData(params);
import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
import 'dart:convert';
void fetchData() async {
const apiUrl = 'https://api.slpy.com/v1/search';
final params = {
'street': 'example_street',
'city': 'example_city',
'region': 'example_region',
'postcode': 'example_postcode',
'country': 'example_country',
'key': 'your_api_key',
};
final uri = Uri.parse(apiUrl).replace(queryParameters: params);
try {
final response = await http.get(uri);
if (response.statusCode == 200) {
final data = json.decode(response.body);
print(data);
} else {
throw Exception('Error: ${response.statusCode}');
}
} catch (error) {
print(error);
}
}
void main() {
runApp(MyApp());
}
class MyApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
fetchData();
return MaterialApp(
home: Scaffold(
appBar: AppBar(
title: Text('API Fetch Example'),
),
body: Center(
child: Text('Check your console for the API response.'),
),
),
);
}
}
Demo Examples
Real world examples and common use cases.
Search Bar
- Adds search bar to a map.
- Fly to result and add marker.
Address Locator
- Geocodes multiple street addresses
- Places markers on the map.
Troubleshooting
No Response
Your Api Key may not be configured correctly.
Open Developer Tools, and look in the Network tab for "search?" files not loading with
status
200.
Click the file and check "Response Headers" for "Reject-Reason:".
Example: "Reject-Reason:Bad Referrer: cdpn.io" not matching "codepen.io" in key's
whitelist.
Next Steps
Enhance your search with Maps or Autocomplete
Reverse Geocoding
- Get a user or device address
- Prefill City or Country
- Find nearby locations
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