Documentation

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

https://api.slpy.com/v1/search?query={search string}&country={country}&key={your_api_key}

Post URL

https://api.slpy.com/v1/search?key={your_api_key}
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

https://api.slpy.com/v1/search?query=400+Broad+St,+Seattle,+WA&country=us&key=abc123

Post URL

https://api.slpy.com/v1/search?key=abc123
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

https://api.slpy.com/v1/search?street={street}&city={city}&region={region}&postcode={postcode}&country={country}&key={your_api_key}

Post URL

https://api.slpy.com/v1/search?key={your_api_key}
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

https://api.slpy.com/v1/search?street=400 Broad St&city=Seattle&region=WA&country=us&language=en&key=abc123

Post URL

https://api.slpy.com/v1/search?key=abc123
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": 10,
	"accuracy": "building",
	"lat": 47.620495,
	"lon": -122.349297,
	"status": "OK",
	"properties": {
		"street": "400 Broad St",
		"neighborhood": "Uptown",
		"sub_city": "Example Town",
		"city": "Seattle",
		"postcode": "98109",
		"district": "King County",
		"district_short": "KN",
		"region": "Washington",
		"region_short": "WA",
		"country_code": "US",
		"country": "United States of America",
		"address": "400 Broad St, Seattle, WA 98109"
	},
	"license": "\u00a9 Slpy \u00a9 OpenStreetMap contributors. Caching\/storage not permitted. Attribution-Terms at https:\/\/slpy.com"
}

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
  • OK : A result was successfully returned.
  • No Results : No Level of result could be found.
  • {Error} : A short error text on incorrect parameters or account issues.
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.

Error Codes

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