How to use the API

Base URL

The base url for all API requests is:

https://api.features4.com/v1/

For accessing a particular API resource you just append its endpoint name to the base path. If, for example, you want to access the number resource you build the requst url as base url and number:

https://api.features4.com/v1/number

note

Please make sure to always use the https protocol, because in order to protect the security of your API keys all requests using the http protocol will fail.

Authentication

Features4 uses API keys to authenticate requests.

Authentication to the API is performed via HTTP Basic Authentication. Provide your API key as the basic auth username value. You do not need to provide a password.

How exactly you provide your username depends on the tool of your choice:

cURL

-u API_TEST_KEY: 
# The colon after your API key prevents cURL from asking for a password.

Python

request.post(..., auth=('API_TEST_KEY', ''))

R

httr.get(..., authenticate("API_TEST_KEY", "")

In the rare case your tool does not provide Basic Authentication you can also construct the corresponding HTTP header yourself:

Just take our API key, add a colon to it, and base64 encode the resulting string. Add this string to the request header.

For example if your API key is API_TEST_KEY, you would base64 encode API_TEST_KEY:, giving you QVBJX1RFU1RfS0VZOg== and set in the request header:

Authorization: Basic QVBJX1RFU1RfS0VZOg==

Examples

Let's say you are interested in the number of bars in a radius of 500m around a given location.

The first thing you need to find is the right API resource and add it to the base URL. In our example that would be the number resource so our URL is:

https://api.features4.com/v1/number

From the API Reference you can see that the number feature takes three input parameters:

• Location (location):
  • Latitude (lat): The latitude in degrees for your location
  • Longitude (lng): The longitude in degrees for your location
• Element (element): The element you want to count
• Radius (radius): The radius around your location in meters

All you need to do is to specify these parameters in the tool of your choice:

cURL

curl https://api.features4.com/v1/number \
  -u API_TEST_KEY: \
  -H "Content-Type: application/json" \
  -d '{"location": {"lat": 48.137, "lng": 11.576}, "element": "bar", "radius": 500}'

Python

import requests

url = "https://api.features4.com/v1/number"

auth = ("API_TEST_KEY", "")

json = {
  "location": {
    "lat": 48.137,
    "lng": 11.576
  },
  "element": "bar",
  "radius": 500
}

r = requests.post(
  url=url,
  json=json,
  auth=auth
)

r.json()

R

library(httr)
library(jsonlite)

url <- "https://api.features4.com/v1/number"

json <- '{
  "location": {
    "lat": 48.137,
    "lng": 11.576
  },
  "element": "bar",
  "radius": 500
}'

body <- fromJSON(
  json,
  simplifyDataFrame = FALSE
)

r <- POST(
  url = url,
  body = body,
  encode = "json",
  authenticate("API_TEST_KEY", "")
)

content(r)

note

Don't forget to add your personal API key. While the API_TEST_KEY in the examples will work, it will only do so for few requests.