Get map guide

Response 200#

application/json.

• typestring · required

  One of brand_position, demand_space_sizes, brand_profile.

• variantstring · nullable · always "position_di"

• titlestring · required

• summarystring · required

• askobject · required

  Show 3 fieldsHide fields

  • methodstring · default "POST"

  • pathstring

    Default: /v1/signals/{signal_id}/datasources/{datasource_id}/datasets/{dataset_id}/map

  • bodyobject · required

• stepsarray of string · required

• notesarray of string · required

• rulesobject · required

  The fixed values a map answer is drawn with, as data.

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

  • sector_coloursarray of string

  • sector_colour_beyondstring · default "#B0B0B0"

    A sector past the eighth.

  • own_brand_colourstring · default "#09B945"

  • profile_coloursmap of array of string

    A competitor's line in a brand profile, in turn, per theme.

  • themesmap of object

    Show 8 fieldsHide fields

    • dotstring · required

    • ghoststring · required

    • textstring · required

    • sector_fillstring · required

    • sector_alphanumber · required

    • sector_strokestring · required

    • driverstring · required

    • averagestring · required

  • reference_radius_pxnumber · default 300

    The map radius every px value here is meant at.

  • dot_pxnumber · default 12

    A dot's diameter.

  • own_dot_pxnumber · 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_scalenumber · default 1.5

    A boundary marker's size, times the dot.

  • label_flip_rnumber · default 1.4

    Past this radius a label moves to the side towards the centre (label_side on each point says which).

  • sizes_rhonumber · default 0.6

  • profile_averagenumber · default 100

  • profile_floor_maxnumber · default 200

    A profile's scale reaches at least this far (profile_scale on the answer says how far it did).

  • labelsobject

    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.

• exampleobject · required

  An answer with made-up brands and figures, as POST …/map gives it.

  Show 9 fieldsHide fields

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

• reference_drawingobject · required

  Show 3 fieldsHide fields

  • languagestring · default "javascript"

  • usagestring

    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.

  • codestring · required

• imageobject · required

  Show 3 fieldsHide fields

  • pngstring · required

  • svgstring · required

  • altstring · 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>.