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
- Python
- R
-u API_TEST_KEY:
# The colon after your API key prevents cURL from asking for a password.
request.post(..., auth=('API_TEST_KEY', ''))
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
- Python
- R
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}'
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()
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.