API Reference

The Features4 API allows you to access a large set of spatial features conveniently using the tools you are already comfortable working with.

It is built around REST and:

  • Uses predictable, resource-oriented URLs.
  • Uses built-in HTTP capabilities for passing parameters and authentication.
  • Accepts JSON-encoded request bodies.
  • Responds with standard HTTP response codes to indicate success or errors.
  • Returns JSON-encoded responses.

Quick start

Getting your first feature is a matter of minutes. Just follow these steps:

  1. Sign up for a Features4 account. Its free.
  2. Log into your dashboard. Copy your private API key from your there.
  3. Copy and paste the code below to make your first request. Please replace API_TEST_KEY with your private API key.
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}'

You need to include an API key as username in HTTP Basic Auth. The colon prevents cURL from asking for a password (for details see: Authentication), otherwise you will receive a 401 - Unauthorized error.

You can use the API key API_TEST_KEY to try out the examples in this reference. However, the number of features you can get is limited. Use your private API key for more features.

Introduction

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

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

Authentication

Features4 uses API keys to authenticate your requests. After signing up for an account, you can view and manage your personal API key in your Dashboard.

Your API key carries many privileges, so be sure to keep it secure! Do not share your private API key in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password. Using curl you would do this by adding the command line option -u API_TEST_KEY:. The colon prevents cURL from asking for a password.

Feature limits

A free Features4 account allows you to use the API for free and obtain a certain number of features. If this limit is exceeded, you will have to wait until the next day until you can make the next request. In this case the API will return a 429 - Too many requests response.

There are three headers in the response that will contain more information about your feature limit:

Header Description
X-Feature-Limit-Limit Your personal feature limit, i.e. the number of features you can request each day
X-Feature-Limit-Features The number of features you requested
X-Feature-Limit-Remaining The number of features you have currently available

You can also view your personal feature limit, the number of features requested so far, and how many features you still have available in your dashboard.

Each feature you request counts towards your personal feature limit. So, for example, if you make one request to an endpoint that returns one individual feature such as the number resource it counts as 1 feature. If you make a request to an endpoint that can return multiple features, e.g. the features resource the number of features depends on your specific request. If you request 5 features, these 5 features are counted towards your feature limit.

API responses

For consistency and ease of usage all responses from the Features4 API have a JSON response body.

HTTP status codes

Features4 uses standard HTTP response codes in the response header to indicate the success or failure of an API request.

In general:

  • Codes in the 2xx range indicate success.
  • Codes in the 4xx range indicate an error due to the information provided (e.g., a required parameter was omitted, falsely specified, etc.).
  • Codes in the 5xx range indicate an error with Features4's servers (these are rare).
HTTP code Description
200 - OK Everything worked as expected.
400 - Bad Request The request could not be completed, often due to a missing required parameter. Learn more
401 - Unauthorized The request could not be authenticated succesfully. Learn more
402 - Request Failed The parameters were valid but the request failed.
403 - Forbidden The API key doesn't carry permissions to perform the request.
404 - Not Found The requested resource doesn't exist (often a typo).
405 - Method not Allowed A request was made with a method that is not supported.
415 - Unsupported Media Type A POST request was made without a Content-Type: application/json header.
429 - Too Many Requests The personal feature request limit was exceeded. Learn more
500, 502, 503, 504 - Server Errors Something went wrong on Feature4's end. (These are rare.)

Features4 uses one custom status code 419 to indicate that currently there is no data available for the country specified by a given location.

Errors

In addition to the HTTP status code in the response header, most errors response bodies contain a message field with more error details in human-readable form, and a code field which can be used to handle errors programmatically.

Authentication error

For authentication errors, Features4 returns the HTTP 401 - Unauthorized status code.

Message Solution
Authentication credentials were not provided Add the header Authorization: Key API_TEST_KEY to your request
Invalid token Make sure you provided your (currently active) API key from your dashboard

Parameter Validation Error

Validation errors are raised as 400 - Bad Request errors. In their body they contain detailed information for each parameter that was invalid.

Feature Limit Error

If you exceed the request feature limit of your account a 429 - Too many requests error is raised. It contains more information on your remaining features.

{
  "error": {
    "message": "Your requested number of features exceeds your feature limit. Number of currently available features: 4",
    "code": "feature_limit_exceeded"
  }
}

Features

Features4 provides many spatial features. Every feature can be accessed on its own with its own dedicated endpoint. For example the Number of elements within a radius feature can be accessed at /number.

If you need to retrieve multiple features for a location, you can simply perform a request for each of them. However, we additionally offer resources to conveniently request multiple features at the same time.

Number

The number of map elements in a given radius around a location of interest

Authorizations:
Request Body schema: application/json
required
LatLng (object) or Address (object)
element
required
string
Enum: "restaurant" "bar" "pub" "fast_food" "ice_cream" "kindergarten" "college" "school" "university" "charging_station" "fuel" "parking" "taxi" "bank" "atm" "clinic" "doctors" "dentist" "hospital" "pharmacy" "arts_centre" "casino" "cinema" "theatre" "marketplace" "place_of_worship" "police" "post_box" "prison" "recycling" "toilets" "fire_station" "convenience" "supermarket" "clothes" "hairdresser" "bakery" "car_repair" "car" "kiosk" "beauty" "hardware" "butcher" "furniture" "mobile_phone" "florist" "electronics" "shoes" "alcohol" "car_parts" "mail" "doityourself" "office" "public_transport" "road" "leisure"

The map element to analyze.

radius
required
integer [ 1 .. 5000 ]

Radius around the location of interest in meters.

Responses

Request samples

Content type
application/json
{
  • "location":
    {
    • "lat": 48.11,
    • "lng": 11.57
    },
  • "element": "bar",
  • "radius": 500
}

Response samples

Content type
application/json
{
  • "name": "number_bar_radius_500m",
  • "value": 24
}

Distance

The distance to the nearest map element from a location of interest

Authorizations:
Request Body schema: application/json
required
LatLng (object) or Address (object)
element
required
string
Enum: "restaurant" "bar" "pub" "fast_food" "ice_cream" "kindergarten" "college" "school" "university" "charging_station" "fuel" "parking" "taxi" "bank" "atm" "clinic" "doctors" "dentist" "hospital" "pharmacy" "arts_centre" "casino" "cinema" "theatre" "marketplace" "place_of_worship" "police" "post_box" "prison" "recycling" "toilets" "fire_station" "convenience" "supermarket" "clothes" "hairdresser" "bakery" "car_repair" "car" "kiosk" "beauty" "hardware" "butcher" "furniture" "mobile_phone" "florist" "electronics" "shoes" "alcohol" "car_parts" "mail" "doityourself" "office" "public_transport" "road" "leisure"

The map element to analyze.

Responses

Request samples

Content type
application/json
{
  • "location":
    {
    • "lat": 48.11,
    • "lng": 11.57
    },
  • "element": "bar"
}

Response samples

Content type
application/json
{
  • "name": "distance_bar_m",
  • "value": 123
}

Area

The sum of the area of map elements in a given radius around a location of interest

Authorizations:
Request Body schema: application/json
required
LatLng (object) or Address (object)
element
required
string
Enum: "restaurant" "bar" "pub" "fast_food" "ice_cream" "kindergarten" "college" "school" "university" "charging_station" "fuel" "parking" "taxi" "bank" "atm" "clinic" "doctors" "dentist" "hospital" "pharmacy" "arts_centre" "casino" "cinema" "theatre" "marketplace" "place_of_worship" "police" "post_box" "prison" "recycling" "toilets" "fire_station" "convenience" "supermarket" "clothes" "hairdresser" "bakery" "car_repair" "car" "kiosk" "beauty" "hardware" "butcher" "furniture" "mobile_phone" "florist" "electronics" "shoes" "alcohol" "car_parts" "mail" "doityourself" "office" "public_transport" "road" "leisure"

The map element to analyze.

radius
required
integer [ 1 .. 5000 ]

Radius around the location of interest in meters.

Responses

Request samples

Content type
application/json
{
  • "location":
    {
    • "lat": 48.11,
    • "lng": 11.57
    },
  • "element": "parking",
  • "radius": 500
}

Response samples

Content type
application/json
{
  • "name": "area_sum_parking_radius_500m",
  • "value": 8130
}

Multiple Features

These resources make it easy to access multiple features for a given location at the same time. The most flexible way is provided using the /features resource

Features

Access multiple features conveniently in a single request.

Authorizations:
Request Body schema: application/json
required
Array of objects

An array with an entry for each feature you request

Responses

Request samples

Content type
application/json
{
  • "features":
    [
    • {
      • "endpoint": "number",
      • "params":
        {
        • "location":
          {
          • "lat": 48.11,
          • "lng": 11.57
          },
        • "element": "bar",
        • "radius": 500
        }
      },
    • {
      • "endpoint": "distance",
      • "params":
        {
        • "location":
          {
          • "lat": 48.11,
          • "lng": 11.57
          },
        • "element": "bar"
        }
      }
    ]
}

Response samples

Content type
application/json
{
  • "features":
    [
    • {
      • "name": "number_bar_radius_500m",
      • "value": 24
      },
    • {
      • "name": "distance_bar_m",
      • "value": 123
      }
    ]
}

Feature Presets

Features presets give you quick access to preselected sets of features related to a specific topic. These are selected manually at the moment but will be selected by machine learning as sets of most important features, e.g. for predicting real estate prices.

Living

A preset of features related to the quality of the living situation.

Authorizations:
Request Body schema: application/json
required
LatLng (object) or Address (object)
max_features
integer >= 1

The maximum number of features you would like to retrieve

Responses

Request samples

Content type
application/json
{
  • "location":
    {
    • "lat": 48.11,
    • "lng": 11.57
    }
}

Response samples

Content type
application/json
{
  • "features":
    [
    • {
      • "name": "distance_doctors_m",
      • "value": 320
      },
    • {
      • "name": "distance_school_m",
      • "value": 55
      },
    • {
      • "name": "distance_kindergarten_m",
      • "value": 240
      },
    • {
      • "name": "distance_cinema_m",
      • "value": 274
      },
    • {
      • "name": "distance_prison_m",
      • "value": 111
      },
    • {
      • "name": "number_restaurant_radius_500m",
      • "value": 3
      },
    • {
      • "name": "number_restaurant_radius_1000m",
      • "value": 10
      },
    • {
      • "name": "number_supermarket_radius_1000m",
      • "value": 9
      },
    • {
      • "name": "number_supermarket_radius_2000m",
      • "value": 12
      },
    • {
      • "name": "number_convenience_radius_2000m",
      • "value": 22
      }
    ]
}

Utilities

Endpoints for utility functions.

ValidElements

A list of map elements that can be used in features

Authorizations:
Request Body schema: application/json
required
LatLng (object) or Address (object)
src
string
Default: "osm_"
Value: "osm_"

The data source to use.

Responses

Request samples

Content type
application/json
{
  • "location":
    {
    • "lat": 48.11,
    • "lng": 11.57
    }
}

Response samples

Content type
application/json
{
  • "elements":
    [
    • "bar",
    • "restaurant",
    • "taxi",
    • "atm"
    ]
}