Darwin public API v1

projects/list experimental

The projects your key may read, in all its organizations.

Any key. The answer holds only what the key reads.

Answers the projects of every organization your key reads, from the oldest to the newest.

Page with page.limit and the nextCursor of the previous page. The last page has no nextCursor. A project created after your first page comes on the last page.

The analytics methods read a project only when its state is computed: an assessment of the project completed. While a new assessment runs, the project stays computed, and the analytics methods read the previous assessment until the snapshot of the new one is sealed.

Params

Result

ProjectSummaryList

Errors

Only the classes of every call.

Examples

A "$projectId" in the params stands for the id of a project your key reads.

The first page

REST:

curl -X POST https://developer.darwindata.ai/public/v1/api/projects/list \
  -H 'Authorization: Bearer <key>' \
  -H 'Content-Type: application/json' \
  -d '{}'

JSON-RPC: send this body to https://developer.darwindata.ai/public/v1/json-rpc, or as a text frame on the WebSocket.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "projects/list",
  "params": {}
}

Two projects per page

REST:

curl -X POST https://developer.darwindata.ai/public/v1/api/projects/list \
  -H 'Authorization: Bearer <key>' \
  -H 'Content-Type: application/json' \
  -d '{"page":{"limit":2}}'

JSON-RPC: send this body to https://developer.darwindata.ai/public/v1/json-rpc, or as a text frame on the WebSocket.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "projects/list",
  "params": {
    "page": {
      "limit": 2
    }
  }
}

projects/describe experimental

The relations projects/query can read, and the columns of one.

Scope projectAnalytics: the project must belong to an organization your key reads.

Answers what projects/query can read in a project: every relation, what one row of it is, and worked queries.

Name a relation in relation to get its columns and their SQL types, read from the snapshot of the project. The relations whose kind is fold are computed from the snapshot for the point of view of the query, most of them aggregations: read them rather than rebuild a total from the tables.

The catalogue is the same for every project. The columns need a sealed snapshot of the project: before the first one, the answer is NOT_READY. They are built within 60 seconds; past it, the answer is UNAVAILABLE: retry later.

Params

Result

ProjectDescription

Errors

NOT_READY, on top of the classes of every call.

Examples

A "$projectId" in the params stands for the id of a project your key reads.

The catalogue

REST:

curl -X POST https://developer.darwindata.ai/public/v1/api/projects/describe \
  -H 'Authorization: Bearer <key>' \
  -H 'Content-Type: application/json' \
  -d '{"projectId":"$projectId"}'

JSON-RPC: send this body to https://developer.darwindata.ai/public/v1/json-rpc, or as a text frame on the WebSocket.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "projects/describe",
  "params": {
    "projectId": "$projectId"
  }
}

The columns of the risks

REST:

curl -X POST https://developer.darwindata.ai/public/v1/api/projects/describe \
  -H 'Authorization: Bearer <key>' \
  -H 'Content-Type: application/json' \
  -d '{"projectId":"$projectId","relation":"fold_risks"}'

JSON-RPC: send this body to https://developer.darwindata.ai/public/v1/json-rpc, or as a text frame on the WebSocket.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "projects/describe",
  "params": {
    "projectId": "$projectId",
    "relation": "fold_risks"
  }
}

projects/query experimental

One read-only SQL query over the analytics of a project.

Scope projectAnalytics: the project must belong to an organization your key reads.

Runs one read-only SQL query over the analytics of a project, and answers its rows as JSON objects, one page at a time.

• sql is one SELECT over the relations of projects/describe, or a UNION, EXCEPT or INTERSECT of them, with an optional WITH. A statement that writes, a second statement, and a read of a file outside the project's own analytics are refused with INVALID_QUERY. So is a query that fails on its own text, and a single row larger than 4 MiB as JSON.
• The query reads the point of view of entityId and its subtree, or of the whole project when entityId is absent, with net or gross ownership.
• It reads the latest sealed snapshot of the project, which can belong to an assessment that still runs. Before the first one, the answer is NOT_READY.

The numbers are the ones the screens compute, with three differences:

• The risks a user excluded are not in fold_risks and risk_rows. The screens keep them in their totals, so a total here can be lower.
• An entity with no dependency data of its own has no row in fold_dependencies. The screens show a sector estimate for it.
• The relations carry no sourcing risk: the screens add it to the commodities.

Limits:

• The relations the query names are built first, within 60 seconds. Past it, the answer is UNAVAILABLE: retry later.
• The query then has 30 seconds. Past it, the answer is QUERY_TIMEOUT. A query that runs out of memory answers QUERY_TOO_LARGE. Narrow the query in both cases, because a retry fails the same way.
• A call waits 5 seconds at most for a free connection, then answers UNAVAILABLE.

Page with page.limit and the nextCursor of the previous page. Send the same sql, entityId and ownershipView with it. The last page has no nextCursor. The cursor counts rows: order the rows on a unique key, or a row can move between two pages. A page stops early when its rows hold more than 4 MiB as JSON: follow its nextCursor. When a new assessment replaces the snapshot between two pages, the cursor answers INVALID_PARAMS: start again from the first page.

Params

Result

RowList

Errors

NOT_FOUND, NOT_READY, INVALID_QUERY, QUERY_TIMEOUT, QUERY_TOO_LARGE, on top of the classes of every call.

Examples

A "$projectId" in the params stands for the id of a project your key reads.

The impact by IPBES pressure

REST:

curl -X POST https://developer.darwindata.ai/public/v1/api/projects/query \
  -H 'Authorization: Bearer <key>' \
  -H 'Content-Type: application/json' \
  -d '{"projectId":"$projectId","sql":"SELECT ipbes_pressure, value FROM dash_ipbes ORDER BY value DESC"}'

JSON-RPC: send this body to https://developer.darwindata.ai/public/v1/json-rpc, or as a text frame on the WebSocket.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "projects/query",
  "params": {
    "projectId": "$projectId",
    "sql": "SELECT ipbes_pressure, value FROM dash_ipbes ORDER BY value DESC"
  }
}

The ten largest pressures, gross

REST:

curl -X POST https://developer.darwindata.ai/public/v1/api/projects/query \
  -H 'Authorization: Bearer <key>' \
  -H 'Content-Type: application/json' \
  -d '{"projectId":"$projectId","ownershipView":"gross","sql":"SELECT pressure_indicator, unit, biome, scope, net FROM fold_pressures ORDER BY abs(net) DESC, pressure_indicator, biome, scope","page":{"limit":10}}'

JSON-RPC: send this body to https://developer.darwindata.ai/public/v1/json-rpc, or as a text frame on the WebSocket.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "projects/query",
  "params": {
    "projectId": "$projectId",
    "ownershipView": "gross",
    "sql": "SELECT pressure_indicator, unit, biome, scope, net FROM fold_pressures ORDER BY abs(net) DESC, pressure_indicator, biome, scope",
    "page": {
      "limit": 10
    }
  }
}

projects/export experimental

One read-only SQL query over the analytics of a project, as a parquet file.

Scope projectAnalytics: the project must belong to an organization your key reads.

Runs one read-only SQL query over the analytics of a project, writes all its rows to one parquet file, and answers a URL to download it. Use it for a relation too large to page with projects/query.

• sql, entityId and ownershipView are those of projects/query, with the same rules and the same three differences from the screens. There is no page and no 4 MiB limit on a row: the file holds every row.
• The answer is url, expiresAt, rows and bytes. Download the file with a plain GET on url, with no header: the URL carries its own signature. It stops working at expiresAt, 15 minutes after the call. Call again for a new URL.
• Each call writes a new file. The storage removes it about one day later.

Limits:

• The relations the query names are built first, within 60 seconds. Past it, the answer is UNAVAILABLE: retry later.
• The query then has 120 seconds. Past it, the answer is QUERY_TIMEOUT. A query that runs out of memory answers QUERY_TOO_LARGE. So does a file that grows past 1 GiB: the query stops there. Narrow the query in both cases, because a retry fails the same way.
• A call waits 5 seconds at most for a free connection, then answers UNAVAILABLE.

Params

Result

ProjectExport

Errors

NOT_FOUND, NOT_READY, INVALID_QUERY, QUERY_TIMEOUT, QUERY_TOO_LARGE, on top of the classes of every call.

Examples

A "$projectId" in the params stands for the id of a project your key reads.

Every dependency row of the project

REST:

curl -X POST https://developer.darwindata.ai/public/v1/api/projects/export \
  -H 'Authorization: Bearer <key>' \
  -H 'Content-Type: application/json' \
  -d '{"projectId":"$projectId","sql":"SELECT * FROM dependency_rows"}'

JSON-RPC: send this body to https://developer.darwindata.ai/public/v1/json-rpc, or as a text frame on the WebSocket.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "projects/export",
  "params": {
    "projectId": "$projectId",
    "sql": "SELECT * FROM dependency_rows"
  }
}