Skip to content
Brasil Data Commons Docs

Query observations (POST)

POST
/v2/observation

Fetch statistical observations for variables over entities.

Request Body required

Section titled “Request Body required ”
Generic observation request
object
variable

Represent a list of entities passed in as plain list or graph expression.

object
dcids
Array<string>
expression
An arrow notation expression Ex: country/USA<-containedInPlace{typeOf: State}
string
formula

Derived-series formulas are not supported: a request that sets this is refused with INVALID_ARGUMENT. The field is kept so the refusal is explicit.

string
entity

Represent a list of entities passed in as plain list or graph expression.

object
dcids
Array<string>
expression
An arrow notation expression Ex: country/USA<-containedInPlace{typeOf: State}
string
formula

Derived-series formulas are not supported: a request that sets this is refused with INVALID_ARGUMENT. The field is kept so the refusal is explicit.

string
date

Date of the observation

  • Not specified: all observations are returned
  • “LATEST”: latest obseration of each facet is returned
  • "": a speficied valid ISO 8601 date. Observation corresponding to this date is returned.
string
value
Value of the observation
string
filter
object
domains

When specified, only observations with provenance in these domains are returned.

Array<string>
facetIds
When specified, only observations with any of these facet ids are returned
Array<string>
select
Fields to return, valid values are: "variable", "entity", "date", "value", "facet"
Array<string>

Responses

Section titled “ Responses ”

200

Section titled “200 ”

A successful response.

object
byVariable
Keyed by variable DCID
object
key
additional properties

Holds all observations of a particular variable.

object
byEntity
Keyed by entity DCID
object
key
additional properties
object
orderedFacets

Facet are orderred by preference.

Array<object>
object
facetId
string
observations
Observations are sorted by date
Array<object>
object
date
date in IOS-8601 format
string
value
number format: double
metadata

Facet contains the source and measurement information for a statistical observation.

object
importName
string
provenanceUrl
string
measurementMethod
string
observationPeriod
string
scalingFactor
string
unit
string
isDcAggregate
boolean
isDcImputed
boolean
metaHash

Hash of the metadata, this is to be used together with a map from the hash to the full metatdata. This is set in /stat/set/within-place/* APIs.

string
facet

Same as meta_hash, used in V1 API.

string
obsCount
Number of observations
integer format: int32
earliestDate
Earliest observation date
string
latestDate
Latest observation date
string
placeTypes

The types of place that the entity is defined as if it is a geographic place This is an experimental field used for usage logging and is not guaranteed to be populated. The absence of values is not a reliable indicator of whether the associated entity is a place.

Array<string>
facets
Keyed by facet ID
object
key
additional properties

Facet contains the source and measurement information for a statistical observation.

object
importName
string
provenanceUrl
string
measurementMethod
string
observationPeriod
string
scalingFactor
string
unit
string
isDcAggregate
boolean
isDcImputed
boolean

default

Section titled “default ”

An unexpected error response.

object
code
integer format: int32
message
string
details
Array<object>
object
@type
string
key
additional properties