Getting started

Your API key, and the first calls to the QC Analytical Results API: health, sending a dataset, listing the charts, one chart, your usage.

Your key

Keys are made on your account page in the Geoscience Analytics Toolkit, under API keys, once your account has API access. Ask [email protected] for access, saying what you plan to build.

  • A key is shown once, when it is made. Copy it then; afterwards only its first characters are listed.
  • Keep it like a password. Anyone with the key can use the API as you. Never put it in a web page, a repository or an email.
  • Give each system its own key, named for it, so you can revoke one without touching the others. An account can hold ten.
  • Revoke a key on the same page. Calls with it stop within a minute.

Send the key with every call, in the Authorization header:

Authorization: Bearer ga_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

(X-API-Key: <key> is accepted too.)

The examples below keep the key in a shell variable, QC_API_KEY, so it never appears in your shell’s history:

read -s QC_API_KEY

1. Is it up?

No key needed.

curl -s https://api.geoscience-analytics.com/v1/health
{"status": "ok", "api_version": "1.0.0", "started": "2026-10-22T06:00:00Z", "up_seconds": 3600}

2. Send your data

A dataset is one of two kinds: precision (duplicate pairs) or accuracy (CRMs and blanks). Send the results as rows with the column names in Datasets, from the same export the app reads. The smallest round trip is a gzipped CSV:

gzip -k -f duplicates.csv
curl -s "https://api.geoscience-analytics.com/v1/datasets?kind=precision" \
  -H "Authorization: Bearer $QC_API_KEY" \
  -H "Content-Type: text/csv" -H "Content-Encoding: gzip" \
  --data-binary @duplicates.csv.gz

The answer (status 201) is the dataset’s id and what it holds; keep the id:

{
  "dataset_id": "ds_a06aac6d1a9afc0fdb880376",
  "kind": "precision",
  "rows": 46104,
  "created_at": "2026-10-22T06:10:00Z",
  "expires_at": "2026-10-22T07:10:00Z",
  "facets": {
    "labs": ["ALS", "SGS"],
    "analytes": ["Ag_MEICP41s_ppm", "Au_AA25_ppm", "..."],
    "suites": ["Expl-Core", "Expl-RC", "..."],
    "stages": ["Crushing Stage", "Field Prep Stage", "Pulverising Stage", "..."],
    "despatches": 166,
    "dates": {"return": {"from": "2022-11-16", "to": "2025-11-10"}, "send": {"from": "2022-10-29", "to": "2025-10-06"}}
  }
}

The facets are the values you can ask charts for: every laboratory, analyte and check stage in the data (CRM types and CRM ids for an accuracy dataset). Sending exactly the same file again gives the same id back, so a client can simply send on every run.

JSON works the same way, with kind in the body:

curl -s https://api.geoscience-analytics.com/v1/datasets \
  -H "Authorization: Bearer $QC_API_KEY" -H "Content-Type: application/json" \
  -d '{"kind": "accuracy", "rows": [{"LABCODE": "ALS", "STANDARDID": "ALS-26", "ASSAYNAME": "Au_AA25_ppm", "ASSAYVALUE": "2.67", "...": "..."}]}'

3. What charts are there?

curl -s https://api.geoscience-analytics.com/v1/charts -H "Authorization: Bearer $QC_API_KEY"

Lists the 18 charts, each with its parameters: name, type, whether it is required, its default, allowed values and range. Charts is the same list with an example for each.

4. A chart

curl -s https://api.geoscience-analytics.com/v1/charts/shewhart \
  -H "Authorization: Bearer $QC_API_KEY" -H "Content-Type: application/json" \
  -d '{"dataset_id": "ds_bbd34394c3dd10abfeebe84d", "lab": "ALS", "analyte": "Au_AA25_ppm",
       "crm_type": "LAB_STD", "crms": ["ALS-26"], "nelson_rules": true}'

Every chart answers with the same envelope around its own spec:

{
  "api_version": "1.0.0",
  "chart": "shewhart",
  "dataset_id": "ds_bbd34394c3dd10abfeebe84d",
  "parameters": {"lab": "ALS", "analyte": "Au_AA25_ppm", "date_type": "return", "x_axis": "check_id",
                 "smoothing_span": 50, "crm_type": "LAB_STD", "crms": ["ALS-26"], "use_certified_values": false, "nelson_rules": true},
  "rows_used": 147,
  "warnings": [],
  "spec": {"chart_type": "shewhart", "points": ["..."], "limits": {"...": "..."}, "nelson": {"...": "..."}, "stats": {"...": "..."}}
}
  • parameters are the parameters as used, defaults filled in: keep them with the chart.
  • rows_used is how many results went into it after the filters.
  • warnings is what the app would have shown in a pop-up for this chart (empty most of the time).
  • spec is the chart: see each chart in Charts.

A date range or a list of despatches narrows the chart; leave both out for everything in the dataset. The lab and analyte names must be exactly as they are in facets.

5. Your usage

curl -s https://api.geoscience-analytics.com/v1/usage -H "Authorization: Bearer $QC_API_KEY"

Your calls by day and endpoint over the last 90 days: how many, the rows they used and the time they took. Your account page shows the month so far and each key’s last 30 days.

On a plan, chart calls stop at the plan’s allowance unless you turn that off on the account page, so nothing beyond the plan is charged: calls past it get 402 allowance_reached until the 1st of next month. You are also emailed when 80% and when all of the month’s chart calls are used (on unless you turn it off).

Request ids

Every answer carries an X-Request-Id header, and every error has request_id in its body. Quote it to [email protected] and we can see what the call asked for, its status and how long it took. The log never holds your key or your data.