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.

Authentication

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:

  • Request Header: Authorization: Bearer <token>
  • Query Parameter: /api/v1/buildings?token=<token>

Examples of the Request Header and Query Parameter Token providing mechanisms are available within each section of the endpoints

Query Buildings by Address

GET /v1/buildings?address=<user-entered-address>

POST /v1/buildings

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.

  • address - User-entered address.
    • Address must contain street address and either zip code or city and state code. Components are separated by comma with optional whitespace.
    • Street address must have building number and street name separated by whitespace
    •
    Response Body

    Query Buildings by Coordinate

    GET /v1/buildings?latitude=<latitude>&longitude=<longitude>

    POST /v1/buildings

    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.

    Token Balance charging

    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.

  • latitude - Latitude of the coordinate.
  • longitude - Longitude of the coordinate.
  • max-distance - Maximum search distance around the coordinate. The default value is 1000 meters (or its equivalent in other distance units).
  • distance-unit - Unit of the max-distance field, and unit of response field distance. The default value is METERS.
    Supported Units:
    • FEET
    • KILOMETERS
    • MILES
    • METERS
    •
    Response Body

    Query Buildings by Region of Interest

    GET /v1/buildings?roi=<GeoJSON>

    POST /v1/buildings

    This endpoint allows an API user to find buildings based on a specified region of interest.

    Token Balance charging

    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.

  • roi - GeoJSON url-encoded geometry.
    •
    Response Body

    Get Token Statistics Summary

    GET /api/v1/client-tokens/current/statistics

    This endpoint allows an API user to receive call statistics data

    Response Body
    • clientTokenId - System client token identifier.
    • currentBalance - Number of requests that an API user has on their balance. A null value indicates an account with unlimited amount of requests.
    • last24h - Number of requests made during the last 24 hours.
    • last24hCharged - Amount charged from token balance during the last 24 hours.
    • sinceDayStart - Number of requests made since beginning of the day by GMT Time Zone.
    • sinceDayStartCharged - Amount charged from balance token since beginning of the day by GMT Time Zone.
    • sinceMonthStart - Number of requests made since the beginning of the current month by GMT Time Zone.
    • sinceMonthStartCharged - Amount charged from token balance since the beginning of the current month by GMT Time Zone.
    • total - Total number of requests made using the specified token.
    • totalCharged - Total amount charged from token balance.
    • byAddress - JSON with detailed statistics for address queries
    • byCoordinate - JSON with detailed statistics for coordinate queries
    • byAddress - JSON with detailed statistics for region of interest queries

    JSON with detailed statistics for each query type has the following shape:

    • last24h - JSON with following attributes:
      • amountCharged - amount charged from token balance
      • requestsCount - number of requests made
    • sinceDayStart - JSON with following attributes:
      • amountCharged - amount charged from token balance
      • requestsCount - number of requests made
    • sinceMonthStart - JSON with following attributes:
      • amountCharged - amount charged from token balance
      • requestsCount - number of requests made
    • total - JSON with following attributes:
      • amountCharged - amount charged from token balance
      • requestsCount - number of requests made

    Restrictions and limits

    Rate quotas

    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.

    Downtime

    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.

    API errors

    Client error
    • Bad Request - 400 - INVALID_ADDRESS: provided address format is not supported
    • Bad Request - 400 - NOT_US_ADDRESS: provided address is not a US address
    • Bad Request - 400 - EXCEEDED_MAX_DISTANCE_VALUE: value of "max-distance" parameter for geo point query exceeds 100000 meters
    • Bad Request - 400 - ROI_IS_MALFORMED: value for "roi" parameter is not a valid GeoJSON
    • Bad Request - 400 - EXCEEDED_TOKEN_REQUESTS_LIMIT: exceeded token requests limit
    • Bad Request - 400 - GEO_POINT_IS_NOT_VALID: invalid latitude or longitude value
    Server error
    • Internal Server Error - 500 - SERVICE_UNAVAILABLE: internal server error
    • Internal Server Error - 500 - BUILDINGS_DATABASE_ERROR: internal server error