---
title: "Query granular native-unit observations"
method: GET
path: "/market-observations"
---

# Query granular native-unit observations

`GET /market-observations`

## Request

- Base URL: `https://narcoscope.com/api/v1`
- URL: `https://narcoscope.com/api/v1/market-observations`
- Auth: none declared

Bounded source-dimension filtering with source locators, dataset hashes, exact units, uncertainty and missing values. Duplicate and unknown parameters are rejected. A valid empty query returns zero matches; missing datasets remain unavailable. Source-specific licenses remain attached.

## Query parameters

- `dataset` 'global-drugs' | 'global-arms-economy'
- `indicator` string
- `geo` string
- `category` string
- `subgroup` string
- `from` string
- `to` string
- `page` integer
- `limit` integer

## Response `200`

Source-bound published data. Partial coverage lists unavailable datasets explicitly.

- object
  - `ok` unknown, required
  - `resource` 'market-observations', required
  - `data` MarketObservations, required
    - `schema` 'narcoscope.market-observations.v1', required
    - `status` 'available' | 'partial' | 'unavailable', required
    - `generatedAt` string, date-time, nullable, required
    - `unavailableDatasets` string[], required
    - `limitations` string[], required
    - `filters` object, required
      - `dataset` 'global-drugs' | 'global-arms-economy', nullable, required
      - `indicator` string, nullable, required
      - `geo` string, nullable, required
      - `category` string, nullable, required
      - `subgroup` string, nullable, required
      - `from` string, nullable, required
      - `to` string, nullable, required
    - `pagination` object, required
      - `page` integer, required
      - `limit` integer, required
      - `total` integer, required
      - `pages` integer, required
      - `nextPage` integer, nullable, required
    - `datasets` object[], required
      - `id` 'global-drugs' | 'global-arms-economy', required
      - `sha256` string, required
      - `generatedAt` string, date-time, required
    - `indicators` object[], required
      - `id` string, required
      - `sourceId` string, required
      - `market` 'drugs' | 'arms' | 'economy', required
      - `label` string, required
      - `unit` string, required
      - `measureType` string, required
      - `description` string, required
      - `limitations` string[], required
      - `datasetId` 'global-drugs' | 'global-arms-economy', required
    - `sources` object[], required
      - `id` string, required
      - `name` string, required
      - `publisher` string, required
      - `url` string, uri, required
      - `downloadUrl` string, uri, required
      - `license` string, required
      - `licenseUrl` string, uri, required
      - `retrievedAt` string, date-time, required
      - `sha256` string, required
      - `bytes` integer, required
      - `notes` string[], required
      - `datasetId` 'global-drugs' | 'global-arms-economy', required
    - `observations` object[], required
      - `id` string, required
      - `indicatorId` string, required
      - `geoCode` string, required
      - `geoName` string, required
      - `geoLevel` 'country' | 'region' | 'city' | 'world', required
      - `period` string, required
      - `category` string, required
      - `subgroup` string, required
      - `value` number, nullable, required
      - `lower` number, nullable, required
      - `upper` number, nullable, required
      - `status` 'reported' | 'estimated' | 'unavailable', required
      - `sourceLocator` string, required
      - `datasetId` 'global-drugs' | 'global-arms-economy', required
      - `sourceId` string, required
      - `unit` string, required
      - `measureType` string, required

## Other responses

- `400`: Invalid resource parameters
- `503`: Typed unavailable evidence; absence is not zero coverage

---

[API](https://skmtc.dev/narcoscope/apis/narcoscope-public-evidence-api.md) · [All operations](https://skmtc.dev/narcoscope/apis/narcoscope-public-evidence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/narcoscope/apis/narcoscope-public-evidence-api/revisions/f70cc53e639d?raw)