Image

Documentation

Learn how to use our API and UI and more.

graphical divider

Querying data with the API

This example will walk through the steps of querying raster or vector data from the API.

Health

Determine whether the server is available with the health endpoint.

curl --request GET \
  https://data.atlasai.co/api/v1/health

If the server is available, a message will be displayed.

Authenticate

To use an existing account authenticate with the authentication endpoint.

curl --header "Content-Type: application/x-www-form-urlencoded" \
  --request POST \
  --data-urlencode 'email=youremail@host.com' \
  --data-urlencode 'password=yourpassword' \
  https://data.atlasai.co/api/v1/authenticate

This endpoint will return user data that is required to use the API. In the remainder of this document it will be assumed that the API token returned by the endpoint has the value yourapitoken. An example return result is presented below.

{
  "user":{
    "name":"your name",
    "email":"youremail@host.com",
    "token":"yourapitoken"
  }
}

Enumerate Datasets

Available datasets are catgorized by the quantities that they measure. These categories are refered to as "indicators" within the API. For example, there may be a single indicator named "Maize Yield" and several corresponding datasets that all measure the yield of maize over different time periods and granularities. The list of available inidcators can be queried with the indicators endpoint.

curl -G --header 'token: yourapitoken'\
  https://data.atlasai.co/api/v1/indicators

Example response:

[
  {
    "id":1,
    "name":"Indicator Name",
    "legendType":null,
    "legendUnits":null,
    "description":"Indicator Description",
    "datasetCategoryId":3,
    "previewThumbnailUrl":null,
    "available":true
  }
]

Indicators themselves are not sufficient to query a specific dataset. However, they can be used to filter the list of available datasets using the datasets endpoint.

curl --header "Content-Type: application/x-www-form-urlencoded" \
  --header 'token: yourapitoken' \
  -G \
  --data-urlencode 'indicatorId=1' \
  https://data.atlasai.co/api/v1/datasets

A partial response is included below. The full return result schema can be found in the full API documentation.

[
  {
    "id":189,
    "dataType":"vector",
    "indicator":"Wealth",
    "aggregationLevel":"District",
    "version":"v1.1.0",
    "timePeriod":"2015-2018",
    "available":true
  }
]

Query

To download a specific dataset two things are required: the dataset ID and the bounding box around which data should be downloaded. The arguments are passed to the datasets-extract endpoint. X and Y arguments correspond to longitude and latitude degrees respectively. Note that the dataset ID is in the request URL. The example cURL request below will download data from the dataset with an ID equal to 189 and will filter the data to within the specified bounding box.

curl --header "Content-Type: application/x-www-form-urlencoded" \
  --header 'token: yourapitoken' \
  --request POST \
  --data-urlencode 'y_min=3.9' \
  --data-urlencode 'y_max=11.2' \
  --data-urlencode 'x_min=-9.06' \
  --data-urlencode 'x_max=2.63' \
  https://data.atlasai.co/api/v1/datasets/189/extract

Upon submitting the extraction request, an email will be sent to the user's email when the download is complete.

Please allow a few moments for the download to complete after being queued.

Icon For Arrow-up