> ## Documentation index
> Fetch the complete documentation index at: https://docs.odysseysignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get map guide

> How to draw one type of map

API versions: v1 (current) https://docs.odysseysignal.com/api/reference/get-map-guide.md

`GET /v1/maps/guide`

What the map shows, the steps to draw it, the fixed values as data, an example answer with made-up brands, a reference drawing (JavaScript, any map answer to an SVG) and a picture of that drawing. Ask a Signal's own map with `POST …/map`. A `variant` is the same type drawn from another kind of metric: `position_di` is a `brand_position` from a Double Index metric.

Authentication: an API key in `X-Api-Key`, or `Authorization: Bearer <token>`.

## Parameters

### Query parameters

- `type` (string, required): The map to draw. One of `brand_position`, `demand_space_sizes`, `brand_profile`.
- `theme` (string, default "light"): The colours of `rules.labels` and `example`. One of `light`, `dark`.
- `variant` (string, nullable, always "position_di"): `position_di` (with `brand_position` only): the map from a `position_di` metric, with guide rings, faded brands outside the norm and "k of m" markets.

## Example request

```bash
curl "https://api.odysseysignal.app/v1/maps/guide?type=brand_position" \
  -H "X-Api-Key: $ODYSSEY_API_KEY"
```

## Response 200

Content: `application/json`.

- `type` (string, required) One of `brand_position`, `demand_space_sizes`, `brand_profile`.
- `variant` (string, nullable, always "position_di")
- `title` (string, required)
- `summary` (string, required)
- `ask` (object, required)
  - `method` (string, default "POST")
  - `path` (string, default "/v1/signals/{signal_id}/datasources/{datasource_id}/datasets/{dataset_id}/map")
  - `body` (object, required)
- `steps` (array of string, required)
- `notes` (array of string, required)
- `rules` (object, required): The fixed values a map answer is drawn with, as data.
  - `orientation` (string, 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.")
  - `sector_colours` (array of string)
  - `sector_colour_beyond` (string, default "#B0B0B0"): A sector past the eighth.
  - `own_brand_colour` (string, default "#09B945")
  - `profile_colours` (map of array of string): A competitor's line in a brand profile, in turn, per theme.
  - `themes` (map of object)
    - `dot` (string, required)
    - `ghost` (string, required)
    - `text` (string, required)
    - `sector_fill` (string, required)
    - `sector_alpha` (number, required)
    - `sector_stroke` (string, required)
    - `driver` (string, required)
    - `average` (string, required)
  - `reference_radius_px` (number, default 300): The map radius every px value here is meant at.
  - `dot_px` (number, default 12): A dot's diameter.
  - `own_dot_px` (number, default 18)
  - `driver_dot_px` ([number, number], at least 2 items, at most 2 items, default [8,20]): A driver's smallest and largest dot; its area follows its share of the largest driver's.
  - `boundary_scale` (number, default 1.5): A boundary marker's size, times the dot.
  - `label_flip_r` (number, default 1.4): Past this radius a label moves to the side towards the centre (`label_side` on each point says which).
  - `sizes_rho` (number, default 0.6)
  - `profile_average` (number, default 100)
  - `profile_floor_max` (number, default 200): A profile's scale reaches at least this far (`profile_scale` on the answer says how far it did).
  - `labels` (object)
    - `font_px` (integer, default 9)
    - `colour` (string, required)
    - `offset_px` (string, default "dot radius + 2")
    - `side` (string, 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.")
    - `collision` (string, 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.")
    - `sizes` (string, default "A size is written bold at 16 px, as a whole percentage (rounded), centred on its point.")
    - `boundary_fill` (string, default "#22293C")
    - `boundary` (string, 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.")
- `example` (object, required): An answer with made-up brands and figures, as `POST …/map` gives it.
  - `type` (string, required) One of `brand_position`, `demand_space_sizes`, `brand_profile`.
  - `theme` (string, required) One of `light`, `dark`.
  - `frame` (object, required)
    - `orientation` (string, 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_circle` (number, default 1)
    - `rings` (array of number)
    - `reference_radius_px` (number, default 300): Every px value in the answer (dots, fonts, offsets) is meant for a map of this radius; scale them with yours.
    - `sectors` (array of objects, required)
      - `id` (integer, required)
      - `label` (string, required)
      - `description` (string, nullable)
      - `start_deg` (number, required)
      - `end_deg` (number, required)
      - `mid_deg` (number, required)
      - `colour` (string, required)
      - `fill` (string, required)
      - `fill_alpha` (number, required)
      - `stroke` (string, required)
    - `sector_labels` (string, 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.")
    - `ribbon` (object, nullable): A band from `inner` to `outer` of the radius in each sector's `colour`. Absent: draw no sector colour at all.
      - `inner` (number, default 0.95)
      - `outer` (number, default 1)
  - `radial` (object, nullable): How a radius became ``draw.rho``: the values the answer was computed with.
    - `scale` (string, required) One of `linear`, `log`, `sigmoid`.
    - `map_limit` (number, required)
    - `log_k` (number, nullable)
    - `sigmoid_midpoint` (number, nullable)
    - `sigmoid_steepness` (number, nullable)
    - `formula` (string, required)
    - `map_limit_auto` (boolean, nullable)
    - `rings` (array of number, nullable)
  - `profile_scale` (object, nullable)
    - `min` (number, required)
    - `max` (number, required)
    - `average` (number, default 100)
    - `formula` (string, default "rho = (value − min) / (max − min); the average is the competitors' 100.")
  - `layers` (array of objects, required)
    - `kind` (string, required) One of `brands`, `drivers`, `sizes`, `profile`, `average`.
    - `label` (string, required)
    - `colour` (string, required)
    - `metric` (string, nullable)
    - `line_px` (number, nullable)
    - `dash` ([number, number], nullable, at least 2 items, at most 2 items)
    - `points` (array of objects, required)
      - `id` (integer or string, required)
      - `label` (string, required)
      - `type` (string, required) One of `brand`, `ghost`, `driver`, `size`, `profile`, `average`.
      - `demand_space` (integer, nullable)
      - `value` (number or object, nullable)
        - `x` (number, required)
        - `y` (number, required)
      - `polar` (object, 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.
        - `r` (number, nullable)
        - `theta` (number, nullable)
        - `phi` (number, nullable)
        - `radius_true` (number, nullable)
        - `outside_map` (boolean, nullable)
      - `draw` (object, required)
        - `rho` (number, required)
        - `bearing_deg` (number, required)
      - `outside_map` (boolean, default false)
      - `radius_true` (number, nullable)
      - `hint` (string, nullable)
      - `size` (number, nullable)
      - `base` (integer, nullable)
      - `own_brand` (boolean, default false)
      - `colour` (string, nullable)
      - `dot_px` (number, nullable)
      - `marker` (string, default "dot") One of `dot`, `boundary`, `text`, `vertex`.
      - `label_side` (string, nullable) One of `above`, `below`.
      - `markets` (integer, nullable)
      - `markets_total` (integer, nullable)
      - `in_net` (boolean, nullable)
      - `low_base` (boolean, nullable)
  - `labels` (object, required)
    - `font_px` (integer, default 9)
    - `colour` (string, required)
    - `offset_px` (string, default "dot radius + 2")
    - `side` (string, 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.")
    - `collision` (string, 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.")
    - `sizes` (string, default "A size is written bold at 16 px, as a whole percentage (rounded), centred on its point.")
    - `boundary_fill` (string, default "#22293C")
    - `boundary` (string, 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.")
  - `legend` (array of objects, required)
    - `label` (string, required)
    - `colour` (string, required)
    - `marker` (string, required) One of `dot`, `line`, `text`.
    - `dash` ([number, number], nullable, at least 2 items, at most 2 items)
  - `meta` (object, required)
    - `figures_rule` (string, 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."): How the figures may be used: as given, never as the input to a new one. The same text on every answer.
    - `period` (object, 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.
      - `granularity` (string, required) One of `month`, `quarter`, `halfyear`, `year`.
      - `last` (integer, required)
      - `ending` (string, required, nullable): The period counted back from, as a period id at `granularity`: the one asked for, or the latest with data.
      - `rolling` (integer, required): Moving-average window in periods; 1 means no smoothing.
      - `complete_only` (boolean, required): False when a last period that has not finished is included.
      - `pooled` (boolean, 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_complete` (boolean, 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.
    - `warnings` (array of string)
    - `query_ids` (array of string)
    - `applied_filters` (array of objects)
      - `dimension` (string, required)
      - `label` (string, required)
      - `origin` (string, 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`.
      - `members` (array of objects, required)
        - `id` (string or integer or boolean, required)
        - `label` (string, required, nullable): Null when this DataSet has no such member; the answer then carries a warning saying so.
        - `role` (string, 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_rows` (boolean, 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.
    - `environment` (string, 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.
- `reference_drawing` (object, required)
  - `language` (string, default "javascript")
  - `usage` (string, default "drawMap(map, size) returns an SVG string of `size` px for any answer of `POST …/map`, every type and both themes. Use it as it is, or as the reference for your own drawing.")
  - `code` (string, required)
- `image` (object, required)
  - `png` (string, required)
  - `svg` (string, required)
  - `alt` (string, required)

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