---
title: "Search for an option within a hierarchical dimension"
method: GET
path: "/dimension-search/datasets/{id}/editions/{edition}/versions/{version}/dimensions/{name}"
tags: ["Public"]
---

# Search for an option within a hierarchical dimension

`GET /dimension-search/datasets/{id}/editions/{edition}/versions/{version}/dimensions/{name}`

Perform a search on dimension options which are within a hierarchy of a published version of a dataset by the ONS.

## Path parameters

- `id` string, required
- `edition` string, required
- `version` string, required
- `name` string, required

## Query parameters

- `limit` integer
- `offset` integer
- `q` string, required

## Response `200`

A json list containing search results of dimension options which are within a hierarchy of a published version of a dataset by the ONS.

- DimensionOptions — The resulting resource of the completed search against a dimension hierarchy.
  - `count` integer, required — The number of items returned.
  - `items` HierarchyDimensionOptionResponse[], required — The results of the completed search against a dimension hierarchy.
    - `code` string, required — The code for this dimension option.
    - `dimension_option_url` string, required — The id of a collection of datasets that a dataset is associated to.
    - `has_data` boolean, required — Indicator to show whether there is an observation value corresponding to the dimension option.
    - `label` string, required — The label for this dimension option.
    - `matches` Matches, required — A list of members and arrays of character offset, defining substrings that matched the search terms.
      - `code` Snippet[] — An array of character offset into the `code` string. These always occur in pairs, and define the start and end of substrings in the member `code` that matched the search terms. The first character of the string is index 1.
        - `start` integer — An integer to define the start of a substring in the member that matched. The first character of the string is index 1.
        - `end` integer — An integer to define the end of a substring in the member that matched.
      - `label` Snippet[] — An array of character offsets into the `label` string. These always occur in pairs, and define the start and end of substrings in the member `label` that matched the search terms. The first character of the string is index 1.
        - `start` integer — An integer to define the start of a substring in the member that matched. The first character of the string is index 1.
        - `end` integer — An integer to define the end of a substring in the member that matched.
    - `number_of_children` integer, required — The number of first generation descendents to this dimension option within the hierarchy.
  - `limit` integer, required — The number of items requested, defaulted to 50 and limited to 1000.
  - `offset` integer, required — The first row of items to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter. The total number of items that one can page through is limited to 1000 items.

## Other responses

- `400` — Failed to process the request due to invalid request.
- `404` — Dimension or option not found.
- `500` — Failed to process the request due to an internal error.

---

[API](https://skmtc.net/office-of-national-statistics/apis/dimension-search-api.md) · [All operations](https://skmtc.net/office-of-national-statistics/apis/dimension-search-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/office-of-national-statistics/dimension-search-api/revisions/372166ddce1a/schema)