Run map

Everything needed to draw one of the DataSet's maps

API version

POST/v1/signals/{signal_id}/datasources/{datasource_id}/datasets/{dataset_id}/map

A brand position, the demand space sizes or a brand profile: the same figures query answers, with the rules to draw them as the portal draws them — the sectors and their names, the radial scale, each point's drawing position (draw.rho, draw.bearing_deg), colours and label placement. Charged as a query of as many rows as it has points.

Authenticate with an API key in X-Api-Key, or a bearer token in Authorization: Bearer <token>.

Parameters#

Path parameters#

signal_idstring · required
datasource_idstring · required
dataset_idstring · required

Request body#

application/json, required.

A map of one DataSet: which map, and the question behind it.

typestring · required
brand_position: brands placed on the demand space map. demand_space_sizes: how large each demand space is. brand_profile: a spider of each brand's strength per demand space.
One of brand_position, demand_space_sizes, brand_profile.
metricstring or array of string · nullable
The catalogue's metric to draw: a position (position/position2, or position_di at its map level) for a brand position, a demand-space index (or a position_di/double_index_net per need area) for a brand profile. A brand profile takes a list too (only when the user asks for several metrics), each metric a line per brand in the same map. Omitted: the DataSet's first such metric.
driversboolean or string or array of string · nullable
Brand position only, and only when the user asks for them (one series per map is the default): the category's drivers, a layer per driver position, each driver sized by its share. true takes every driver position in the DataSet's catalogue (a study asks the drivers' relation and relevance as positions of their own, and the portal draws them together); a string or a list names them.
sizesboolean · default false
Brand position only, and only when the user asks for it: each demand space's size, written in its sector.
periodobject
The time window. A dimension, but with first-class syntax.
rolling is the moving-average window in periods. It is part of the question, not a display setting: a smoothed value and an unsmoothed one are different numbers, and a base read beside a smoothed value covers the same window.
Show 5 fieldsHide fields
- granularitystring
  Omit for the Signal's standard unit where the DataSet has it, else the data project's own; the answer's meta.period says which was used.
  One of month, quarter, halfyear, year.
- lastinteger · ≥ 1 · ≤ 120 · default 1
  How many periods, counting back from ending. Above 1, a row that stands for one period of the window (a moving average is a series, one row per period) carries that period as a dimension, and the answer declares its column, even when group_by names no period; a window pooled into one figure carries none. Group by the period for one row per period every time. A driver's position has one place rather than one per period: it is answered for the last period only (as last: 1), and meta.warnings says so.
- endingstring · nullable
  Last period to include, named by any day in it: a period id as the API writes one (2026-09, 2026-Q3, 2026-H2, 2026) or a date. Omit for the latest available.
- rollinginteger · ≥ 1 · ≤ 12
  Moving-average window in periods (1 = none); the windows allowed per unit are in discovery. Omit for the portal's preset for the unit (discovery period.defaults_by_granularity).
- complete_onlyboolean
  Exclude a trailing period that has not finished; an open question then ends at the last finished period, as the portal does. Omit for the portal's preset for the unit.
filtersmap of array of string or integer or boolean
As dimensions.filters on a query.
entitiesarray of integer or string · nullable
As on a query: the brands to draw. Omitted: the Signal's standard set.
focusarray of integer or string · nullable
As on a query: brands to add and mark as the caller's own.
themestring · default "light"
One of light, dark.

Example request#

Shell

curl -X POST "https://api.odysseysignal.app/v1/signals/{signal_id}/datasources/{datasource_id}/datasets/{dataset_id}/map" \
  -H "X-Api-Key: $ODYSSEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "brand_position"
  }'

Response 200#

application/json.

typestring · required
One of brand_position, demand_space_sizes, brand_profile.
themestring · required
One of light, dark.
frameobject · required
Show 7 fieldsHide fields
- orientationstring
  Default: Bearing 0° is straight up and bearings run clockwise. A point is drawn at (cx + rho·R·sin(bearing), cy − rho·R·cos(bearing)) for a map of radius R; rho 1 is the outer circle.
- outer_circlenumber · default 1
- ringsarray of number
- reference_radius_pxnumber · default 300
  Every px value in the answer (dots, fonts, offsets) is meant for a map of this radius; scale them with yours.
- sectorsarray of objects · required
  Show 10 fieldsHide fields
  - idinteger · required
  - labelstring · required
  - descriptionstring · nullable
  - start_degnumber · required
  - end_degnumber · required
  - mid_degnumber · required
  - colourstring · required
  - fillstring · required
  - fill_alphanumber · required
  - strokestring · required
- sector_labelsstring
  Default: Each sector's label along its arc, 12 px outside the outer circle, bold 13 px, in `labels.colour` (the theme's text colour), never in the sector's colour.
- ribbonobject · nullable
  A band from inner to outer of the radius in each sector's colour. Absent: draw no sector colour at all.
  Show 2 fieldsHide fields
  - innernumber · default 0.95
  - outernumber · default 1
radialobject · nullable
How a radius became draw.rho: the values the answer was computed with.
Show 8 fieldsHide fields
- scalestring · required
  One of linear, log, sigmoid.
- map_limitnumber · required
- log_knumber · nullable
- sigmoid_midpointnumber · nullable
- sigmoid_steepnessnumber · nullable
- formulastring · required
- map_limit_autoboolean · nullable
- ringsarray of number · nullable
profile_scaleobject · nullable
Show 4 fieldsHide fields
- minnumber · required
- maxnumber · required
- averagenumber · default 100
- formulastring
  Default: rho = (value − min) / (max − min); the average is the competitors' 100.
layersarray of objects · required
Show 7 fieldsHide fields
- kindstring · required
  One of brands, drivers, sizes, profile, average.
- labelstring · required
- colourstring · required
- metricstring · nullable
- line_pxnumber · nullable
- dash[number, number] · nullable · at least 2 items · at most 2 items
- pointsarray of objects · required
  Show 21 fieldsHide fields
  - idinteger or string · required
  - labelstring · required
  - typestring · required
    One of brand, ghost, driver, size, profile, average.
  - demand_spaceinteger · nullable
  - valuenumber or object · nullable
    Show 2 fieldsHide fields
    xnumber · required
    ynumber · required
  - polarobject · nullable
    The same point in polar form, as the map draws it.
    Derived from x/y, so it is context rather than a measurement: r is the distance from the centre, theta the angle from the x-axis counter-clockwise and phi the angle from the top clockwise — the one the demand spaces are cut by — all in radians.
    radius_true and outside_map come only from a method that keeps the map's edge as a boundary rather than a position (position2): a brand beyond the edge is drawn on it, r is then the edge, and radius_true how far out it really is. Absent, not null, otherwise.
    Show 5 fieldsHide fields
    rnumber · nullable
    thetanumber · nullable
    phinumber · nullable
    radius_truenumber · nullable
    outside_mapboolean · nullable
  - drawobject · required
    Show 2 fieldsHide fields
    rhonumber · required
    bearing_degnumber · required
  - outside_mapboolean · default false
  - radius_truenumber · nullable
  - hintstring · nullable
  - sizenumber · nullable
  - baseinteger · nullable
  - own_brandboolean · default false
  - colourstring · nullable
  - dot_pxnumber · nullable
  - markerstring · default "dot"
    One of dot, boundary, text, vertex.
  - label_sidestring · nullable
    One of above, below.
  - marketsinteger · nullable
  - markets_totalinteger · nullable
  - in_netboolean · nullable
  - low_baseboolean · nullable
labelsobject · required
Show 8 fieldsHide fields
- font_pxinteger · default 9
- colourstring · required
- offset_pxstring · default "dot radius + 2"
- sidestring
  Default: `label_side` on each point: in the top half of the map a point further out than r 1.4 is labelled below, any other above; the bottom half the other way round.
- collisionstring
  Default: Keep a label next to its dot. When it would cover another label, a dot or a size, try its other side, then right and left of the dot, a little further out at each round; never hide one. A label that ended up more than about 12 px from its dot gets a thin line to it.
- sizesstring
  Default: A size is written bold at 16 px, as a whole percentage (rounded), centred on its point.
- boundary_fillstring · default "#22293C"
- boundarystring
  Default: A `boundary` marker is a hollow ring 1.5× the dot, filled with `boundary_fill` (the map ground), with a 2 px edge in the layer's colour and, inside it, a chevron in that colour pointing outwards: nothing of it reaches past the ring. `hint` is its tooltip.
legendarray of objects · required
Show 4 fieldsHide fields
- labelstring · required
- colourstring · required
- markerstring · required
  One of dot, line, text.
- dash[number, number] · nullable · at least 2 items · at most 2 items
metaobject · required
Show 6 fieldsHide fields
- figures_rulestring
  How the figures may be used: as given, never as the input to a new one. The same text on every answer.
  Default: Use only the figures in this answer, exactly as given, each with its label, metric, market and period. Never compute a new figure from them: no ratio, no share of a share (such as consideration among those aware), no conversion rate, no difference or change between two figures (give both and say which is higher), no sum, no average, no index. Never estimate, round differently or fill a gap: a figure that is not in an answer is not available, so say so. Every claim, explanation and conclusion must rest on the answers; do not invent reasons the data does not give. Before presenting, check every figure again against the answer it came from and correct or drop any that does not match.
- periodobject · nullable
  The window the answer covers, every field resolved.
  Echoed because a question may leave any of it open and the defaults depend on the Signal and the DataSet, so a client presenting the figures does not have to work them out again.
  Show 7 fieldsHide fields
  - granularitystring · required
    One of month, quarter, halfyear, year.
  - lastinteger · required
  - endingstring · required · nullable
    The period counted back from, as a period id at granularity: the one asked for, or the latest with data.
  - rollinginteger · required
    Moving-average window in periods; 1 means no smoothing.
  - complete_onlyboolean · required
    False when a last period that has not finished is included.
  - pooledboolean · default false
    Present, and true, only when the window spans several periods and each figure covers all of it as one span (the portal's "whole period pooled"), so no row names a period: unsmoothed, and not broken down by period. Group by period for a figure per period.
  - last_completeboolean · nullable
    Whether the last period the answer holds (ending) had finished by the latest data the Signal may read: false means its figures cover only the months so far. Left out when the waves are not dated.
- warningsarray of string
- query_idsarray of string
- applied_filtersarray of objects
  Show 4 fieldsHide fields
  - dimensionstring · required
  - labelstring · required
  - originstring · required
    request when the question named these members; signal_default when it left the filter open and the Signal's default filled it in (its standard market, its default competitors: see the DataSet's defaults); default when it left the filter open and the answer covers every member available to it.
    One of request, signal_default, default.
  - membersarray of objects · required
    Show 4 fieldsHide fields
    idstring or integer or boolean · required
    labelstring · required · nullable
    Null when this DataSet has no such member; the answer then carries a warning saying so.
    rolestring · nullable
    On a brand: focus when the question named it in focus, standard_brand when it is the Signal's standard brand, added because the question named no focus. Absent otherwise.
    One of focus, standard_brand.
    has_rowsboolean · default true
    Present, and false, only when the rows break the answer down by this dimension and none of them is this member: the answer has no data for it, and a warning names it.
- 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.

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>.

Status	Code	When
400	`invalid-request`	The request is not valid for this DataSet; `detail` says why.
401	`unauthorized`	No credential, or one that is not accepted.
403	`forbidden`	The credential is valid but does not cover what was asked.
404	`not-found`	Nothing there, or nothing this credential may read.
422	`validation-failed`	The request does not match the contract; `errors` lists each field.
429	`rate_limited`	Too many requests, or the monthly quota is used up.
503	`unavailable`	A service behind the API did not answer; try again.