Index Values

List the index series catalog and stored values, fetch published values on demand into the shared store, and enter values by hand with a quote and a source.

Index values are the external half of a price: the public numbers a contract's formulas read. Four routes manage them. GET /v1/price-baseline/indices is the series catalog with stored ranges, GET /v1/price-baseline/indices/values reads stored values, POST /v1/price-baseline/indices/refresh fetches published values from their publishers, and POST /v1/price-baseline/indices/manual stores hand-entered values with their source. A series is identified by a key; a key of the form manual:<name> names a series entered by hand.

Every stored value has a source: a publisher family (behg, bundesbank, destatis, eex, dwd, eurostat, bafa, the, bls, eia, singstat, law), library, manual, or invoice. Published values are shared by every workspace. Values entered by hand, printed on the biller's invoice, or read from a workspace library are workspace-scoped, and so is eex_web_rnd, a research feed read from the EEX website. An invoice value is usable but never independent.

GET/v1/price-baseline/indices

Response fields

data[].keystringSeries key.

data[].labelstringHuman-readable name.

data[].providerstringPublisher family, for example bundesbank, destatis, eex, law, manual.

data[].unit / base_year / notestring | integer | stringUnit, base year when the series has one, and a note.

data[].storedobject | nullcount, first and last period stored. Null when no value is stored.

GET/v1/price-baseline/indices/values

Query parameters

seriesstringComma-separated series keys.

Response fields

data[].series / periodstringThe observation. period is YYYY, YYYY-MM, YYYY-Qn or YYYY-Hn.

data[].value / unitnumber / string | nullThe value and its unit.

data[].sourcestringWhere the value comes from; see the source list above.

data[].source_url / quote / document_idstring | nullThe publisher URL and the publisher's own line, or the workspace document that carries the value.

data[].base_yearinteger | nullBase year of the published series, when the source states it.

cURL: Read stored values for two series

curl "https://api.talonic.com/v1/price-baseline/indices/values?series=destatis.erdgas.boerse,eex.eua.month" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

POST/v1/price-baseline/indices/refresh

Body fields

series*string[]Series keys to fetch. 1 to 50 entries.

from_year*integerFirst year, 2000 to 2100.

to_year*integerLast year, 2000 to 2100.

Response fields (201)

data[].seriesstringThe series key.

data[].storedintegerValues stored.

data[].errorstring | nullWhy the series could not be fetched.

data[].statusstringok, error, pending (waits on a publisher job) or need (needs a person). Absent for library series.

cURL: Fetch two years of one series

curl -X POST "https://api.talonic.com/v1/price-baseline/indices/refresh" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"series": ["destatis.erdgas.boerse"], "from_year": 2024, "to_year": 2025}'

indices/refresh writes shared data. The fetched values are stored as published values that every workspace reads, so a refresh by one workspace changes the index tables of all. The fetch runs inside the request, and a long range of a slow publisher can approach the HTTP timeout. Fetch in smaller year ranges when a publisher is slow.

POST/v1/price-baseline/indices/manual

Body fields

values*object[]1 to 500 values.

values[].series*stringSeries key, up to 120 characters.

values[].period*stringYYYY, YYYY-MM, YYYY-Qn or YYYY-Hn.

values[].value*numberThe value.

values[].quote*stringThe published line or passage carrying the value. Up to 4000 characters.

values[].source_urlstring | nullPublisher URL. Either a source URL or a document is required.

values[].document_iduuid | nullA workspace document. When given, the quote must occur in it and print the value (422 otherwise).

values[].unit / base_yearstring | integer | nullUnit and base year of the value.

cURL: Enter a value from a publisher page

curl -X POST "https://api.talonic.com/v1/price-baseline/indices/manual" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "values": [
      {
        "series": "manual:fernwaerme-index",
        "period": "2025-03",
        "value": 118.4,
        "unit": "Index",
        "source_url": "https://example.org/index/2025-03",
        "quote": "Maerz 2025: 118,4"
      }
    ]
  }'

The response is { "stored": <count> } with status 201. Because validation is all or nothing, a single invalid value (for example a quote that does not occur in the named document) rejects the whole call with a 422 and stores nothing, which keeps the workspace's index tables free of half-applied entries.

Frequently asked questions

Does fetching index values affect other workspaces?+

Yes. Values fetched from a publisher are stored as published values shared by every workspace, so POST /v1/price-baseline/indices/refresh changes the index tables all workspaces read. Values entered through indices/manual belong to the workspace alone.

What does a manual index value need?+

A quote plus either a source URL or a workspace document. When a document is given, the quote must occur in it and print the value. The series must be known to the catalog, and a manual:<name> key is accepted for a series that only exists in the workspace.

What happens if one value of a manual batch is invalid?+

Nothing is stored. The values are validated in order and the call is all or nothing, so a 422 on one value rejects the whole batch.

Why can a refresh report errors but still succeed?+

A series that cannot be fetched is reported with its error while the other series are still stored. Read the status of each entry in the response: ok, error, pending when a publisher job is outstanding, or need when a person must supply the value.

Series Sync and Data Quality

Assumptions

Open Inputs and Enrichment

Index Values

Frequently asked questions

Related