---
title: "Query dataset"
method: POST
path: "/{dataset}/{version}"
tags: ["Data"]
---

# Query dataset

`POST /{dataset}/{version}`

## Request

- Base URL: `https://agnitio.emsicloud.com`
- URL: `https://agnitio.emsicloud.com/{dataset}/{version}`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://auth.emsicloud.com/connect/token` scopes: `agnitio`

Agnitio data queries are performed by assembling a JSON description of the query and POSTing it to the specific dataset you wish to query.
The query structure has two required fields: `metrics` and `constraints`.

The `metrics` field is an array of objects which describe which metrics you would like queried and returned.
These objects have a required `name` field which specifies which metric is desired. They also have an optional `as` field
which allows you to determine what the metric is called in the response.

The `constraints` field is an array of objects which describe how the dimensions of the dataset should be limited and aggregated.
The `map` field in the request constraints maps from the codes defined by the dimension's taxonomy to user defined values that will be returned in the response.

In addition to the `map` field, you can use a shorthand option as well known as `mapLevel` to roll out a given parent to all of its children as individual mappings at a specified level.

The API also supports operations like Location Quotient and Shift Share, as well as sorting, offsets, and limits for pagination.

## Path parameters

- `dataset` string, required
- `version` string, required

## Request body

- object
  - `metrics` object[], required: An array of objects which describe which metrics you would like queried and returned.
    - `name` string, required: Specifies which metric is desired.
    - `as` string: Allows you to determine what the metric is called in the response.
    - `operation` object: Optional operation to perform on the metric
      - `name` 'LocationQuotient' | 'ShiftShare': Location Quotient: measure of geographical concentration applied to summable measures such as jobs or establishments. Can be calculated on datasets with an `Area` dimension. Shift Share: attempts to explain what factors cause a change in a measure over time. Use on datasets with an `Area` dimension and metrics with a time component:
      - `geoparent` string: The code of a parent value in the area dimension; use national or containing state, for example.
      - `along` string: The dimension to perform the comparison along. Usually `Industry` or `Occupation`.
      - `base` string: The start metric for the comparison. Used with ShiftShare
  - `constraints` object[], required: An array of objects which describe how the dimensions of the dataset should be limited and aggregated.
    - `dimensionName` string, required
    - `map` object: Maps from the codes defined by the dimension's taxonomy to user defined values that will be returned in the response.
    - `mapLevel` object: Shorthand for mapping all children at a specified level.
      - `level` integer
      - `predicate` integer[]
  - `sortBy` object[]: Return responses in a sorted order.
    - `name` string
    - `direction` 'ascending' | 'descending'
  - `offset` integer: Pagination offset
  - `limit` integer: Pagination limit

## Response `200`

OK

- object
  - `data` object[], required
    - `name` string
    - `type` string
    - `rows` union[]
      - union
        - string
        - number
  - `errors` unknown[], required
    - unknown
  - `timings` string[], required
  - `totalRows` integer, required

---

[API](https://skmtc.dev/lightcast/apis/core-lmi-agnitio.md) - [All operations](https://skmtc.dev/lightcast/apis/core-lmi-agnitio/llms.txt) - [OpenAPI document](https://skmtc.dev/lightcast/apis/core-lmi-agnitio/revisions/9624111295e3?raw)