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.

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.

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.

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:

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.

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

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).

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

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.

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"
  }
}

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.

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 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.