Developers

AkilIQ data API

Read the datasets your organisation publishes, or the sample dataset, over HTTPS with an API key.

Quick start

Create an API key on the API page. A sandbox key reads the sample dataset and is never charged.

Set three environment variables: the data API's address, your key and the dataset's ID.

# Your deployment's data API address
export AKILIQ_API_URL=http://localhost:8080
# The key, shown once when it was created
export AKILIQ_API_KEY=akq_test_...
# The dataset's ID, from the API page
export AKILIQ_DATASET=ds_...

Run an example. Each one is published exactly as it is tested against the API.

#!/usr/bin/env bash
# The five newest notices from Kenya and Uganda.
# Needs AKILIQ_API_URL, AKILIQ_API_KEY and AKILIQ_DATASET in the environment.
curl --fail-with-body --silent --show-error --get \
  -H "Authorization: Bearer $AKILIQ_API_KEY" \
  --data-urlencode 'q={"select":["reference","title","country","published_on"],"filters":[{"field":"country","operator":"in","value":["KE","UG"]}],"sort":[{"field":"published_on","direction":"desc"}],"limit":5}' \
  "$AKILIQ_API_URL/v1/datasets/$AKILIQ_DATASET/rows"

Page through a dataset

Every page but the last carries next_cursor. Send it back as cursor, with the same filters and sort, for the next page.

#!/usr/bin/env bash
# Every health notice, highest value first, ten a page, following next_cursor.
# Needs curl, jq, and AKILIQ_API_URL, AKILIQ_API_KEY and AKILIQ_DATASET.
set -euo pipefail
query='{"select":["reference","estimated_value"],"filters":[{"field":"sector","operator":"eq","value":"Health"}],"sort":[{"field":"estimated_value","direction":"desc"}],"limit":10}'
cursor=""
while :; do
  body=$(jq -c --arg cursor "$cursor" 'if $cursor == "" then . else . + {cursor: $cursor} end' <<<"$query")
  page=$(curl --fail-with-body --silent --show-error \
    -H "Authorization: Bearer $AKILIQ_API_KEY" \
    -H "Content-Type: application/json" \
    --data "$body" \
    "$AKILIQ_API_URL/v1/datasets/$AKILIQ_DATASET/query")
  jq -r '.data[] | "\(.reference) \(.estimated_value)"' <<<"$page"
  cursor=$(jq -r '.next_cursor // ""' <<<"$page")
  [[ -n "$cursor" ]] || break
done

Endpoints

Method	Path	What it does
`GET`	`/v1/datasets/{dataset_id}/rows`	Read a page of a published dataset's rows.
`POST`	`/v1/datasets/{dataset_id}/query`	Query a published dataset with the specification in the request body.

Read the full reference

Versioning

Every path begins with /v1/. A change that could break an integration is never made to v1: it is published as a new version beside it.

Additions, such as a new endpoint, header, response field or error code, arrive in v1 and are listed in the changelog. Write clients that ignore what they do not know.

Changelog and deprecation policy

OpenAPI document

The OpenAPI 3.1 document is generated from the data API's implementation and checked against the running API on every change to its code.

Download the OpenAPI document