Query observations (POST)

POST

/v2/observation

• Same-origin path behind the stack Caddy (proxies to the mixer). Used by the in-page Try-it playground.
• Public production endpoint.

Fetch statistical observations for variables over entities.

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

Supported operators for the formula expression: +, -, *, /, along with parentheses. The items of the formula have a form of “StatVar[OptionalFilters]”.

The following filters are supported:

1. mm: MeasurementMethod
2. op: ObservationPeriod
3. ut: Unit
4. sf: ScalingFactor

For example:

1. Person_Count - Person_Count_Female
2. Person_Count_Female / Person_Count[mm=CensusACS5yrSurvey;op=P5Y]
3. Person_Count - Person_Count_Female - Person_Count_Male[op=P5Y]
4. (Person_Count_Male - Person_Count_Female) / Person_Count

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

Supported operators for the formula expression: +, -, *, /, along with parentheses. The items of the formula have a form of “StatVar[OptionalFilters]”.

The following filters are supported:

1. mm: MeasurementMethod
2. op: ObservationPeriod
3. ut: Unit
4. sf: ScalingFactor

For example:

1. Person_Count - Person_Count_Female
2. Person_Count_Female / Person_Count[mm=CensusACS5yrSurvey;op=P5Y]
3. Person_Count - Person_Count_Female - Person_Count_Male[op=P5Y]
4. (Person_Count_Male - Person_Count_Female) / Person_Count

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

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

An unexpected error response.

object

code

integer format: int32

message

string

details

Array<object>

object

@type

string

key

additional properties