# Data query API

## Request conventions

The gateway path prefix is `/api/relic`. All POST endpoints below perform read operations.

| Field          | Definition                                                    |
| -------------- | ------------------------------------------------------------- |
| Accept-Version | Request header. The current contract version is 1.            |
| datasetRef     | Opaque dataset handle generated by the service                |
| page.cursor    | Continuation cursor from page.cursor in the previous response |
| page.limit     | Number of entries per page                                    |

## Endpoints

| Method and path              | Content                                                    |
| ---------------------------- | ---------------------------------------------------------- |
| POST /api/relic/search       | Search results grouped by activity, with dataset summaries |
| POST /api/relic/lookup       | Batch dataset details                                      |
| GET /api/relic/sources       | Catalog of sources, versions and system models             |
| POST /api/relic/lci          | Cumulative elementary flow inventory for a dataset         |
| POST /api/relic/lcia         | LCIA results for a dataset                                 |
| POST /api/relic/lcia-methods | LCIA method catalog for a source and version               |

## Search fields

| /search request field   | Definition                                                      |
| ----------------------- | --------------------------------------------------------------- |
| query                   | Optional keywords for reference products, names or descriptions |
| filters.sources         | Source and version scope                                        |
| filters.models          | System model scope                                              |
| filters.locations       | Geographic code scope                                           |
| filters.activityTypes   | Activity type scope                                             |
| filters.classifications | Classification scope                                            |
| sort                    | name or relevance; relevance requires a nonempty query          |
| page                    | Cursor and page size; at most 100 entries per page              |

Fields are combined with AND. Multiple values within one field are combined with OR. data is an activity array, datasets
contains the corresponding dataset summaries, and page.total counts matching activities.

## Lookup fields

| /lookup request field | Definition                                                        |
| --------------------- | ----------------------------------------------------------------- |
| datasetRefs           | Array of dataset handles; mutually exclusive with coordinates     |
| coordinates           | Array of coordinates, each containing id, version and systemModel |
| include               | documentation and provenance; both are included by default        |

A request may contain at most 200 items. Missing records return found: false.

The following fields describe geography and reference products in dataset details. See
[Geographies](/en/resources/file-definitions#geographies) and [model catalog columns](/en/resources/file-definitions#database-overview) for the
corresponding XLSX representation.

| /lookup response field  | Definition                             |
| ----------------------- | -------------------------------------- |
| location.id             | Dataset geography identifier           |
| location.name           | Geographic name                        |
| location.path           | Recorded geographic path; may be empty |
| referenceProduct.amount | Reference product quantity             |
| referenceProduct.unit   | Reference product unit                 |

## Result fields

| Endpoint      | Main request fields                                         | Main response fields                                               |
| ------------- | ----------------------------------------------------------- | ------------------------------------------------------------------ |
| /lci          | datasetRef; optional type, name, flowCategory, page         | flow, amount, unit, direction                                      |
| /lcia         | datasetRef; optional methodId, categories, indicators, page | method, value, unit                                                |
| /lcia-methods | source; optional version, query, page                       | methodId, name, category, indicator, unit, version in data.methods |

| Query         | Maximum page size | Result scope                                                                         |
| ------------- | ----------------: | ------------------------------------------------------------------------------------ |
| /lci          |               200 | Cumulative elementary flows, excluding the reference product; missing units are null |
| /lcia         |               200 | Results for the impact assessment method, impact category and category indicator     |
| /lcia-methods |               500 | Impact assessment method catalog for the source and version                          |

In cumulative LCI, amount / unit represents an elementary flow quantity and its unit. In LCIA, value / unit represents
an impact assessment result and its category indicator unit.

For /lcia, methodId, categories and indicators come from the corresponding source's method catalog. methodId is the
complete [Method ID](/en/resources/file-definitions#impact-categories), not a standalone [Method UUID](/en/resources/file-definitions#lcia-methods).

## Response

| Field           | Content                                                           |
| --------------- | ----------------------------------------------------------------- |
| data            | Query data; structure depends on the endpoint                     |
| page            | cursor, limit, total; an empty cursor means there is no next page |
| meta            | Contract version, language and release collection metadata        |
| restricted      | Result restriction flag for /lci and /lcia                        |
| data.restricted | Catalog restriction flag for /lcia-methods                        |
| error           | code, message, field, details, requestId                          |

Without authorization for commercial data, /lci and /lcia return empty data and restricted: true. /lcia-methods returns
empty methods and data.restricted: true. The query API does not return unit process direct exchanges, supplier shares or
characterization factor value tables.