> For the complete documentation index, see [llms.txt](https://api-docs.ihme.services/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.ihme.services/api/data-collection.md).

# Data collection

Data collection is an abstraction over a family of several datasets of different types grouped together under some principle.

## Properties

| Property      | Type        | Description                                                                     |
| ------------- | ----------- | ------------------------------------------------------------------------------- |
| `id`          | `int`       | Unique data collection identifier                                               |
| `name`        | `string`    | Data collection name                                                            |
| `description` | `string`    | Short description of the underlying data                                        |
| `datasets`    | `Dataset[]` | List of datasets available in the collection. See the `Dataset` structure below |

### Dataset properties

| Property                   | Type                 | Description                                                                                                                               |
| -------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data_type`                | `string`             | One of the available eight data types                                                                                                     |
| `granularity`              | `Map<string, int[]>` | Dataset granularity describing the available filters and their values                                                                     |
| `value_fields`             | `string[]`           | Available value fields. Typically, we'll see `value`, `lower`, and `upper`. Which represent the mean value and the uncertainty boundaries |
| `forecast_start_years_map` | `Map<int, int>`      | Mapping from round ids to the corresponding years when the forecast data starts. Is empty for non-forecast data                           |

The table above contains all properties relevant to the API user; any undocumented properties can safely be ignored.

## Example

```
{
    "id": 414, 
    "name": "GBD - HIV/AIDS, 1990-2017, global",
    "description": "HIV/AIDS cause and sequela, Global, 1990-2017, All age groups, All units/measures",
    "datasets": [
        {
            "data_type": "cause_outcome",
            "granularity": {
                "age_group_id": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 23, 24, 25, 26, 28, 30, 31, …],
                "cause_id": [298, 300, 948, 949, 950],
                "forecast_scenario_id": [1],
                "gender_id": [1, 2, 3],
                "location_id": [1],
                "measure_id": [1, 2, 3, 4, 5, 6],
                "metric_id": [1, 3],
                "round_id": [5],
                "year": [1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, …]
            },
            "value_fields": ["value", "upper", "lower"],
            "forecast_start_years_map": {4: 2017}
        },
        {
            "data_type": "sequela_outcome",
            "granularity": {
                "age_group_id": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 23, 24, 25, 26, 28, 30, 31, …],
                "gender_id": [1, 2, 3],
                "location_id": [1],
                "measure_id": [3, 5, 6],
                "metric_id": [1, 3],
                "round_id": [5],
                "sequela_id": [22682, 5108, 5099, 5102, 5105, 6482, 5120, 5111, 5114, 5117, 6479, 5132, 5123, 5126, 5129, 6485, 5087, …],
                "year": [1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, …]
            },
            "value_fields": ["value", "upper", "lower"],
            "forecast_start_years_map": {}
        }
    ]
}
```

## Endpoints

The `DataCollection` entity has the following endpoints:

* [Get data collections shared with my organization](/api/data-collection/get-my-organization-data-collections.md)
* [Get primary entity and round specific granularity](/api/data-collection/get-data-collection-granularity.md)
* [Query data collection data](/api/data-collection/query-data-collection-data.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://api-docs.ihme.services/api/data-collection.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.