Get Shared Map Endpoint

GET

/maps/shared/{token}

const url = 'https://example.com/maps/shared/example';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://example.com/maps/shared/example

Get a shared map by token. Optionally authenticated for non-public layers.

SEC-S08 (Phase 1062-05): emits Content-Security-Policy: frame-ancestors 'self' [<allowed_origins>...] on the response, derived from the active EmbedToken for this map. When no EmbedToken exists or allowed_origins is empty, defaults to frame-ancestors 'self'. The SecurityHeadersMiddleware respects this route-level CSP and skips emitting X-Frame-Options: DENY.

fix(#394) SH-01/B-023: accepts X-Embed-Token so embed viewers get the layers the token’s scope authorizes (SEC-022 capability posture).

Authorizations

Parameters

Path Parameters

token

required

Token

string

Header Parameters

X-Embed-Token

Any of:

string
null

string

Optional embed token — includes its scoped dataset layers when valid for this map.

Responses

200

Successful Response

application/json

SharedMapResponse

object

name

required

Name

string

description

required

Any of:

string
null

string

center_lng

required

Center Lng

number

center_lat

required

Center Lat

number

zoom

required

Zoom

number

bearing

required

Bearing

number

pitch

required

Pitch

number

basemap_style

required

Basemap Style

string

show_basemap_labels

Show Basemap Labels

boolean

default: true

basemap_config

Any of:

BasemapConfig
null

BasemapConfig

object

label_mode

BasemapLabelMode

Basemap label prominence.

string

default: full

Allowed values: full subtle hidden

road_visibility

BasemapSublayerVisibility

Road and transit sublayer visibility where supported.

string

default: full

Allowed values: full subtle hidden

boundary_visibility

BasemapSublayerVisibility

Administrative boundary sublayer visibility where supported.

string

default: full

Allowed values: full subtle hidden

building_visibility

Building Visibility

Whether supported building/3D building basemap layers are shown.

boolean

default: true

land_water_tone

BasemapLandWaterTone

Land and water color treatment where supported.

string

default: default

Allowed values: default muted contrast monochrome

relief_contrast

Any of:

BasemapReliefContrast
null

BasemapReliefContrast

string

Allowed values: soft standard strong

opacity

Opacity

Master basemap opacity 0.0-1.0

number

default: 1 <= 1

background_color

Any of:

string
null

string

sublayer_overrides

Any of:

object
null

object

key

additional properties

SublayerOverride

Per-sublayer style override for a single basemap sublayer.

All fields are nullable — a None value means “use the basemap default”. Only #RRGGBB hex strings are accepted for color fields; None means the basemap default color is preserved. Numeric ranges are clamped at validation time (Pydantic ge/le constraints).

The key set of BasemapConfig.sublayer_overrides is treated as opaque (forward-compatible with future sublayer IDs) — see CONTEXT.md D-01.

Security: extra=“forbid” locks the D-14 scope guardrail: unknown style axes such as dash patterns, line caps, halo blur, and text-font are rejected at validation time (T-1059A-03).

object

stroke_color

Any of:

string
null

string

stroke_width

Any of:

number
null

number

<= 20

casing_color

Any of:

string
null

string

casing_width

Any of:

number
null

number

<= 20

min_zoom

Any of:

number
null

number

<= 24

max_zoom

Any of:

number
null

number

<= 24

opacity

Any of:

number
null

number

<= 1

basemap_position

Any of:

BasemapPosition
null

BasemapPosition

Whether the basemap renders below (‘bottom’, default) or above (‘top’) data layers.

string

Allowed values: bottom top

projection

Any of:

BasemapProjection
null

BasemapProjection

Map projection. ‘mercator’ (default) or experimental ‘globe’.

string

Allowed values: mercator globe

terrain_config

Any of:

TerrainConfig
null

TerrainConfig

object

enabled

Enabled

boolean

source_dataset_id

Any of:

string
null

string format: uuid

exaggeration

Exaggeration

number

default: 1 <= 3

has_non_public_layers

Has Non Public Layers

boolean

legend_title

Any of:

string
null

string

layers

required

Layers

Array<object>

SharedLayerResponse

object

required

string

dataset_id

required

Dataset Id

string

dataset_name

required

Dataset Name

string

display_name

Any of:

string
null

string

table_name

required

Table Name

string

geometry_type

required

Any of:

string
null

string

column_info

Any of:

Array<object>
null

Array<object>

object

key

additional properties

any

sort_order

required

Sort Order

integer

visible

required

Visible

boolean

opacity

required

Opacity

number

paint

required

Paint

object

key

additional properties

any

layout

required

Layout

object

key

additional properties

any

layer_type

Layer Type

string

default: vector_geolens

dataset_record_type

Any of:

string
null

string

filter

Any of:

Array
null

Array

label_config

Any of:

object
null

object

key

additional properties

any

popup_config

Any of:

PopupConfig
null

PopupConfig

Per-layer popup configuration: enable/disable + custom title template

ordered visible-fields allowlist. Persisted as JSONB on map_layers.

object

enabled

required

Enabled

boolean

expression

Any of:

string
null

string

<= 500 characters

visible_fields

Any of:

Array<string>
null

Array<string>

<= 100 items

style_config

Any of:

object
null

object

key

additional properties

any

show_in_legend

Show In Legend

boolean

default: true

tile_url

required

Tile Url

string

is_dem

Any of:

boolean
null

boolean

dem_vertical_units

Any of:

string
null

string

is_3d

Any of:

boolean
null

boolean

feature_count

Any of:

integer
null

integer

tile_version

Any of:

integer
null

integer

dataset_attribution

Any of:

string
null

string

Example

{
  "show_basemap_labels": true,
  "basemap_config": {
    "label_mode": "full",
    "road_visibility": "full",
    "boundary_visibility": "full",
    "building_visibility": true,
    "land_water_tone": "default",
    "relief_contrast": "soft",
    "opacity": 1,
    "basemap_position": "bottom",
    "projection": "mercator"
  },
  "terrain_config": {
    "enabled": false,
    "exaggeration": 1
  },
  "has_non_public_layers": false,
  "layers": [
    {
      "layer_type": "vector_geolens",
      "show_in_legend": true
    }
  ]
}

400

Bad request — invalid payload

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

401

Unauthorized — missing or invalid credentials

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

403

Forbidden — caller lacks access to this resource

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

404

Not found

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

409

Conflict — resource state prevents the operation

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

410

Gone — the resource existed but is no longer available

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

422

Validation error

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

429

Too many requests — retry after the advertised interval

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

Headers

Retry-After

integer

Seconds until the request may be retried

500

Internal server error

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

503

Service unavailable — the database could not serve the request

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

Privacy Apache 2.0 getgeolens.com