Getting Started
The EarthDefine Buildings API is organized using REST architecture. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
The EarthDefine Buildings API is organized using REST architecture. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
The EarthDefine Buildings API uses API Tokens to authenticate requests.
To receive an API Token, please contact EarthDefine at: buildings@earthdefine.com.
Your API tokens carry privileges, so be sure to keep them secure! Do not share your secret API token in publicly accessible areas such as GitHub, client-side code, and so forth.
There are two options you can provide to your API Token within a request:
Examples of the Request Header and Query Parameter Token providing mechanisms are available within each section of the endpoints
The endpoint allows an API user to find buildings based on an entered address.
The system tolerates user-made typos and mistakes within the address field automatically.
This endpoint allows an API user to find buildings based on a specified coordinate.
Returned buildings will be sorted by distance to the specified coordinate.
When querying API by coordinate, token balance will
be charged for an amount equal to the number of
buildings returned by the API. The number of credits
the current request is charged is returned in the
"X-Request-Cost" response header.
If no buildings are found near coordinate, token
balance will be decreased by 1.
This endpoint allows an API user to find buildings based on a specified region of interest.
When querying API by region of interest, token
balance will be charged for an amount equal (unique
addresses - 5) but not less than 1. The number of
credits the current request is charged is returned
in the "X-Request-Cost" response header.
If no buildings are found within the specified
region of interest, token balance will be decreased
by 1.
This endpoint allows an API user to receive call statistics data
JSON with detailed statistics for each query type has the following shape:
We support 50 calls/second/token for your license period. You can reuse the token on multiple endpoints simultaneously within the quota limit. When the limit is reached, you will receive a “Too many requests” error.
Scheduled downtimes will be communicated to users 1 week prior to the event. We will send out an additional reminders 48 hours and 24 hours before the event.
2024 © All Rights Reserved.