Query observations

GET

/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.

Parameters

Query Parameters

variable.dcids

Array<string>

variable.expression

string

An arrow notation expression Ex: country/USA<-containedInPlace{typeOf: State}

variable.formula

string

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

entity.dcids

Array<string>

entity.expression

string

An arrow notation expression Ex: country/USA<-containedInPlace{typeOf: State}

entity.formula

string

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

date

string

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.

value

string

Value of the observation

filter.domains

Array<string>

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

filter.facetIds

Array<string>

When specified, only observations with any of these facet ids are returned

select

Array<string>

Fields to return, valid values are: “variable”, “entity”, “date”, “value”, “facet”

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