Using the API

Everything the portal does for you in the browser, your own scripts can do with an API key: upload a survey, choose lines, check them, submit, follow the jobs and download the results. The steps and the rules are the same as in the portal; only the way you sign in is different.

API keys

• Make a key on the Account page, under API keys. Give it a name that says where it will be used, for example "nightly upload script".
• The key is shown once. Copy it when it appears and keep it in a password manager or your system's secret store. We keep only a fingerprint of it, so nobody, including our staff, can show it to you again. A lost key is revoked and replaced.
• A key acts for your organisation. It can do what a signed-in user of your organisation can do in the portal, and nothing for any other organisation. It cannot make, list or revoke keys, and it cannot change a password: those need a signed-in user.
• Revoke a key on the Account page when a script is retired or the key may have been seen by someone else. It stops working at once. Our staff can also revoke a key if they see it misused.
• Keys start with cky_. Never put one in a web address, a shared document or a code repository; send it only in the Authorization header shown below.

Sending requests

Use the same address you open the portal at, and send the key with every request. The examples below use the curl command line tool and two shell variables:

export BASE="https://your-portal-address/app"
export APIKEY="cky_..."   # from the Account page
AUTH="Authorization: Bearer $APIKEY"

Every answer is JSON, except the downloads. To check the key, ask who it acts for:

curl -s -H "$AUTH" "$BASE/api/me"

1. Upload a survey

Send each file as the body of a request, with its file name. The first file starts a new upload and the answer gives its upload_id; send any further files of the same survey (for example the .dat after the .dfn) with that id. The same file formats and size limit apply as in the portal.

curl -s -H "$AUTH" --data-binary @survey.dfn \
  "$BASE/api/uploads?filename=survey.dfn"
# the answer includes "upload_id": "3f0c..."
curl -s -H "$AUTH" --data-binary @survey.dat \
  "$BASE/api/uploads?filename=survey.dat&upload_id=3f0c..."

When the answer's status is ready it lists the survey's lines, its data columns and the coordinate check. If the coordinates need a choice, make it in the portal for that upload, or contact support.

2. Choose lines and check them

Name up to 60 lines, the target depth in metres and the field type (magnetic_tmi or gravity_gz). The answer is a selection with a batch_id, one row per line, with the reason when it cannot be processed. See choosing a target depth.

curl -s -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"lines": ["1010", "1020"], "target_depth": 300,
       "field": "magnetic_tmi"}' \
  "$BASE/api/uploads/3f0c.../lines"

To change the target depth or leave a line out, check the selection again:

curl -s -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"target_depth": 400}' \
  "$BASE/api/batches/BATCH_ID/quote"

3. Submit

Submit the selection. Each line becomes one job.

curl -s -H "$AUTH" -H "Content-Type: application/json" \
  -d '{}' \
  "$BASE/api/batches/BATCH_ID/submit"
# "submitted": [{"line": "1010", "job_id": "9b2e...", ...}, ...]

4. Follow the jobs

curl -s -H "$AUTH" "$BASE/api/jobs/9b2e..."
curl -s -H "$AUTH" "$BASE/api/jobs"      # all of your jobs

A job's status is processing, then in_review while our staff review the result, then ready. A line that could not be processed says refused or failed with the reason in status_text (lines not processed). Results are reviewed by people, so allow time: ask every few minutes, not every few seconds.

5. Download the results

When the job is ready, download every file of its report set in one .zip, or one file by name from the job's files list (reading your results).

curl -s -H "$AUTH" -o results.zip \
  "$BASE/api/jobs/9b2e.../download.zip"
curl -s -H "$AUTH" -OJ "$BASE/api/jobs/9b2e.../files/targets.csv"

6. Or send one line yourself

If your own software already has a line as values at equal station spacing, it can skip the upload and send the line as a job of its own. These requests go to the service address without /app, under your organisation's id: the tenant_id in the answer to /api/me above. A key only ever works under its own organisation's id; any other id answers 403.

export ROOT="https://your-portal-address"
export ORG="acme"   # "tenant_id" from /api/me

Put the line in a file, for example line.json: the field values station by station, from the first, as profile, and as parameters the station spacing in metres (dx), the field type and the target depth in metres. The service chooses everything else, and a request that tries to set more is refused (422).

{"profile": [-812.4, -811.9, -810.7, ...],
 "parameters": {"dx": 25, "field": "magnetic_tmi", "target_depth": 300}}

Submit it. The answer is the new job with its id, and its state:

curl -s -H "$AUTH" -H "Content-Type: application/json" -d @line.json \
  "$ROOT/tenants/$ORG/jobs"
# "id": "5d1a...", "state": "queued", ...

Ask for the job until its state is succeeded and released is true (or refused or failed, with the reason in refusal). Its artefacts then list the files to download by name: result.json holds each target's position, depth and spread. A line sent this way gets that file rather than the report set of a survey upload. Delete a job you no longer need:

curl -s -H "$AUTH" "$ROOT/tenants/$ORG/jobs/5d1a..."
curl -s -H "$AUTH" -o result.json \
  "$ROOT/tenants/$ORG/jobs/5d1a.../artefacts/result.json"
curl -s -H "$AUTH" -X DELETE "$ROOT/tenants/$ORG/jobs/5d1a..."

A job sent this way shows in the portal's job list too.

Limits and answers

A key has the same per-organisation limits as the portal (uploads open at once and per hour, line selections, checks and submissions per minute, lines per day), and each key at most 300 requests a minute. Sending one line yourself (section 6) counts toward the same submissions per minute and lines per day as the portal. Over a limit the answer is 429. When the answer has a Retry-After header (the per-key limit, making keys, and submissions per minute when sending one line yourself), wait that many seconds; otherwise wait a minute, or until the next hour or day for the hourly and daily limits, then try again.

Every refusal carries a detail in plain words, the same words the portal shows.