Get dataset

Response 200#

application/json.

• environmentstring · nullable

  The data environment the answer was read in, prod or test: the one Odyssey set on the Signal, or the one an Odyssey person picked for this call.

• idstring · required

• typestring · required

• namestring · required

• descriptionstring · nullable

• datasource_idstring · required

• contract_versionstring · required

• periodobject · required

  How this DataSet may be asked about time. The period is a dimension with first-class syntax, so it is described here rather than sitting only in the request schema.

  Show 13 fieldsHide fields

  • standardobject · required

    The standard period: what a question that names no period is answered at, as the portal opens. Use it unless the user asks for another period.

    Show 4 fieldsHide fields

    • granularitystring · required

    • rollinginteger · required

      Moving-average window; 1 means none.

    • complete_onlyboolean · required

    • labelstring · required

      The portal's name for it, e.g. "Quarter, smoothed (4)".

  • optionsarray of objects · required

    Every period this DataSet can be asked about, as the portal's period selector offers them: the standard first, then the other windows at its unit, then the coarser units, then the finer ones. Send one as period (with last and ending as needed); nothing outside this list is answered.

    Show 4 fieldsHide fields

    • granularitystring · required

    • rollinginteger · required

      Moving-average window; 1 means none.

    • complete_onlyboolean · required

    • labelstring · required

      The portal's name for it, e.g. "Quarter, smoothed (4)".

  • granularitiesarray of string · required

    Granularities this DataSet may be asked for, finest first.

  • default_granularitystring · required

    What a question that names no granularity is answered at: the Signal's standard unit, else the data project's.

  • smallest_bucketstring · required

    The bucket the data is stored at. Nothing finer can be asked for; anything coarser is rolled up.

  • max_periodsinteger · required

    Upper bound on period.last.

  • default_periodsinteger · required

  • max_rollinginteger · required

    Upper bound on period.rolling, the moving-average window in periods. 1 means no smoothing.

  • default_rollinginteger · required

    period.rolling when the question leaves it out, at default_granularity. Other units: defaults_by_granularity.

  • rolling_optionsmap of array of integer · required

    The period.rolling values allowed at each granularity of this DataSet, as in the portal. 1 means no smoothing; any other value is refused.

  • default_complete_onlyboolean · required

    period.complete_only when the question leaves it out, at default_granularity.

  • defaults_by_granularitymap of object · required

    The portal's preset per unit: what rolling and complete_only are when a question names that unit and leaves them out. The answer echoes what was run in meta.period.

    Show 2 fieldsHide fields

    • rollinginteger · required

    • complete_onlyboolean · required

  • ending_formatstring · required

    Format of period.ending. Omit ending for the latest available period.

• languagesarray of string

  Languages this DataSet can be read in. Perception only — a survey is translated and the other datasets carry one vocabulary everywhere, so an empty list means the question does not arise rather than that none is available. The DataSource's language is which of these answers come back in.

• metric_countinteger · required

  How many metrics this DataSet publishes to this caller. Enough to decide whether to fetch them, which is why the list itself is a separate request.

• metrics_urlstring · required

  Where this DataSet's metrics and their groups are described. Its own endpoint because the list is long — a perception dataset publishes a metric per configured question and each carries the parameters a query needs — and because a caller browsing DataSets is not yet reading metrics.

• dimensionsarray of objects · required

  Show 9 fieldsHide fields

  • idstring · required

  • namestring · required

  • descriptionstring · nullable

  • kindstring · required

    categorical | temporal | entity | derived

  • filterableboolean · required

  • groupableboolean · required

  • multi_selectboolean · required

    Whether a filter on this dimension accepts several values.

  • valuesarray of string · nullable

    Members, inline, when they are a closed list the API defines. Otherwise null — fetch values_url.

  • values_urlstring · nullable

    Where to enumerate this dimension's members. Present when they come from the data rather than from a fixed list, because which values exist differs per DataSource.

• query_urlstring · required

  Where to POST a query against this DataSet. Published so a client never assembles an action path itself — the one path it cannot get wrong silently.

• defaultsobject · nullable

  What an open question is answered with on this Signal: unit, market, brands, and where each comes from. Only on the Signal-rooted path.

  Show 7 fieldsHide fields

  • granularitystring · required

    The unit of a question that names none (also period.default_granularity).

  • granularity_sourcestring · required

    signal when the Signal's standard unit, data_project when the project's, api otherwise.

    One of signal, data_project, api.

  • marketobject · required · nullable

    The market a question that names none, and does not break down by market, is answered for. Null: the figures pool every market in pooled_markets, and the answer warns.

    Show 3 fieldsHide fields

    • idinteger · required

    • labelstring · required

    • sourcestring · default "signal" · always "signal"

      Who set it: Odyssey, on the Signal.

  • pooled_marketsinteger · required

    How many markets an open question pools when there is no standard market.

  • competitorsobject · required · nullable

    The brands a question that names none covers. Null: every brand this Signal may read.

    Show 5 fieldsHide fields

    • methodstring · required

      list: the brands in brands. top: the count brands ranked highest by rank_metric over the latest twelve months of data, whatever period the question asks, for the markets it runs with, as the portal's top-N; ranked when a question needs them.

      One of list, top.

    • brandsarray of integer · nullable

      Brand ids of a list set (labels: list_brands or the dimension values).

    • countinteger · nullable

    • rank_metricstring · nullable

      The metric key a top set is ranked by.

    • sourcestring · default "signal" · always "signal"

  • own_brandsobject · nullable

    The customer's own brands. Null: the Signal names none. With several, ask which one a question is about.

    Show 3 fieldsHide fields

    • brandsarray of integer · required

      The customer's own brands this Signal may read. A question about one of them names it in focus.

    • standardinteger · nullable

      The own brand added to the default competitors of a question without focus, as the portal adds its active brand. Null: none is added.

    • sourcestring · default "signal" · always "signal"

  • notesarray of string

    Each Signal setting that is not applied here, and why.

Errors#

Errors are application/problem+json (RFC 9457): type, title, status, detail and, for some, more fields that say how to fix the call. The type is https://api.odysseysignal.app/problems/<code>.