Query observations

/v2/observation is the endpoint you’ll reach for most: it returns values of a statistical variable for one or more places.

The request

You need three things:

variable.dcids — what to measure (e.g. Count_Person).
entity.dcids — where (e.g. country/BRA), or entity.expression to expand a relation.
select — which fields to return; repeat for each (entity, variable, value, date).

Add date=LATEST to get the most recent value.

curl -G "https://brazildatacommons.com.br/core/api/v2/observation" \
  --data-urlencode "variable.dcids=Count_Person" \
  --data-urlencode "entity.dcids=country/BRA" \
  --data-urlencode "date=LATEST" \
  --data-urlencode "select=entity" \
  --data-urlencode "select=variable" \
  --data-urlencode "select=value" \
  --data-urlencode "select=date"

import requests

BASE = "https://brazildatacommons.com.br/core/api"
resp = requests.get(
    f"{BASE}/v2/observation",
    params=[
        ("variable.dcids", "Count_Person"),
        ("entity.dcids", "country/BRA"),
        ("date", "LATEST"),
        ("select", "entity"),
        ("select", "variable"),
        ("select", "value"),
        ("select", "date"),
    ],
)
resp.raise_for_status()
print(resp.json()["byVariable"])

const BASE = "https://brazildatacommons.com.br/core/api";
const qs = new URLSearchParams();
qs.append("variable.dcids", "Count_Person");
qs.append("entity.dcids", "country/BRA");
qs.set("date", "LATEST");
for (const f of ["entity", "variable", "value", "date"]) qs.append("select", f);

const res = await fetch(`${BASE}/v2/observation?${qs}`);
const data = await res.json();
console.log(data.byVariable);

Try it live

Edit any value and press Run. Newlines in a value expand to a repeated parameter (that’s how select gets its four entries):

GET /v2/observation

GET URL

/core/api/v2/observation?variable.dcids=Count_Person&entity.dcids=country%2FBRA&date=LATEST&select=entity&select=variable&select=value&select=date

All states in Brazil at once

Swap entity.dcids for an entity.expression to expand a relation — here, every state containedInPlace Brazil:

GET /v2/observation

GET URL

/core/api/v2/observation?variable.dcids=Count_Person&entity.expression=country%2FBRA%3C-containedInPlace%7BtypeOf%3AState%7D&date=LATEST&select=entity&select=variable&select=value&select=date

Discovering variables

Don’t know a variable’s DCID? Search for it, then feed the result back in above:

GET /v1/variable/search

GET URL /core/api/v1/variable/search?query=population

Query observations

The request

Try it live

All states in Brazil at once

Discovering variables

See also