---
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}`

## Request

- Base URL: `/v1` (relative, and the document’s source URL is not known)
- URL: `/v1/dimension-search/datasets/{id}/editions/{edition}/versions/{version}/dimensions/{name}`
- Auth: none declared

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.dev/office-of-national-statistics/apis/dimension-search-api.md) - [All operations](https://skmtc.dev/office-of-national-statistics/apis/dimension-search-api/llms.txt) - [OpenAPI document](https://skmtc.dev/office-of-national-statistics/apis/dimension-search-api/revisions/372166ddce1a?raw)