Encode geometry. Read spatial references.

Server access and keys

Generate a server API key in Account settings with a Free account. Access is currently free within operating limits and is subject to change.

Use a confidential server key in Authorization: Api-Key <secret>. Store it in your backend environment or secret store. Keep it out of browser code, iframe URLs and source control.

Account access, any configured expiry, revocation and operation permissions are checked on each server operation. To rotate a key, issue a replacement, update your integration and then revoke the old key. The full key is shown only when issued. Signing in to this website does not replace an integration credential.

Embedding a map instead? Geometry Embed uses a separate publishable key; that key cannot authorize server API calls.

Your first server request

curl --request POST \
  --url https://spatialglobe.com/api/v1/encode \
  --header "Authorization: Api-Key $SPATIALGLOBE_SERVER_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "geometry": {
    "type": "Point",
    "coordinates": [
      11.575,
      48.137
    ]
  }
}'

curl --request POST \
  --url https://spatialglobe.com/api/v1/encode \
  --header "Authorization: Api-Key $SPATIALGLOBE_SERVER_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "geometry_kind": "segment",
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [
        11.575,
        48.137
      ],
      [
        11.576,
        48.138
      ]
    ]
  },
  "precision": {
    "code_length": 20
  }
}'

curl --request POST \
  --url https://spatialglobe.com/api/v1/encode \
  --header "Authorization: Api-Key $SPATIALGLOBE_SERVER_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "geometry_kind": "route",
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [
        11.575,
        48.137
      ],
      [
        11.5751,
        48.13705
      ],
      [
        11.5752,
        48.1371
      ]
    ]
  }
}'

curl --request POST \
  --url https://spatialglobe.com/api/v1/encode \
  --header "Authorization: Api-Key $SPATIALGLOBE_SERVER_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "geometry_kind": "rectangle",
  "geometry": {
    "type": "Point",
    "coordinates": [
      11.575,
      48.137
    ]
  },
  "parameters": {
    "heading_deg": 45,
    "length_m": 20,
    "width_m": 10
  }
}'

curl --request POST \
  --url https://spatialglobe.com/api/v1/encode \
  --header "Authorization: Api-Key $SPATIALGLOBE_SERVER_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "geometry_kind": "polygon",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          11.575,
          48.137
        ],
        [
          11.5753,
          48.13705
        ],
        [
          11.57525,
          48.1372
        ],
        [
          11.57495,
          48.13718
        ],
        [
          11.575,
          48.137
        ]
      ]
    ]
  },
  "precision": {
    "code_length": 24
  }
}'

curl --request POST \
  --url https://spatialglobe.com/api/v1/encode \
  --header "Authorization: Api-Key $SPATIALGLOBE_SERVER_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "geometry_kind": "vector",
  "geometry": {
    "type": "Point",
    "coordinates": [
      11.575,
      48.137
    ]
  },
  "parameters": {
    "azimuth_deg": 90,
    "elevation_angle_deg": 15,
    "displacement_m": 100
  }
}'

curl --request POST \
  --url https://spatialglobe.com/api/v1/decode \
  --header "Authorization: Api-Key $SPATIALGLOBE_SERVER_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "srl": "!D6GX-USMO-BKBK"
}'

The page does not send these requests or collect keys. Copy an example into your own backend environment.

Geometry reference

Positions are WGS84 [longitude, latitude] in degrees. Send finite numbers and exactly two coordinates per position. Distances, radii, elevations and displacements are in meters; speeds are in meters per second; angles are in degrees.

An encode request contains geometry, optional geometry_kind, parameters, precision and options. Unknown fields are rejected. If omitted, the kind follows GeoJSON: Point → point, LineString → route, Polygon → polygon.

Representation and precision

precision: {"code_length": N} selects a code-character budget, excluding separators and generation markers. Explicit precision is supported for polygons and segments only.

• Segments: 16, 20 or 24 characters; default 16.
• Polygons with three or four vertices: 16, 20 or 24; default 16. Five or six vertices require 28; default 28.
• Other kinds use their standard representation and reject an explicit precision field.

Inputs are quantized to representable values. Code length is not a universal accuracy guarantee, and a geometry can fail if it cannot fit the chosen representation. Use decoded coordinates and parameters from the response for the geometry actually represented.

Responses and the SRL to keep

{
  "data": {
    "srl": "!D6GX-USMO-BKBK",
    "public_srl": "!D6GX-USMO-BKBK",
    "public_generation": null,
    "public_url": "https://srl.gl/!D6GX-USMO-BKBK",
    "public_url_display": "https://srl.gl/!D6GX-USMO-BKBK",
    "geometry_kind": "point",
    "geometry": {
      "type": "Point",
      "coordinates": [
        11.57500248377426,
        48.13700286341344
      ]
    },
    "parameters": {
      "radius_m": 0.0
    },
    "requested_parameters": {},
    "transport_codes": []
  },
  "meta": {
    "api_version": "v1"
  }
}

Persist and exchange data.public_srl. It includes the public generation marker when one is required. Keep that marker: do not strip it or parse internal code headers yourself. Most references are currently provisional; use the geometry guide for the current development context.

A rectangle or vector uses a Point anchor plus its physical parameters. That Point alone is not the full shape. Full-SRL decode uses the same result fields, without transport_codes, and with empty requested_parameters.

Compute calls and iframe handoff do not create account Library entries. Your application remains responsible for saving its own records and business associations.

Short transport codes need context

The server API can return E6, E8 and E9 as secondary transport representations of a surface point without radius. They do not replace the full SRL and cannot encode arbitrary geometry. The standard geometry picker has no E-Code mode.

{
  "geometry": {
    "type": "Point",
    "coordinates": [
      11.575,
      48.137
    ]
  },
  "options": {
    "transport_profiles": [
      "E6",
      "E8",
      "E9"
    ]
  }
}

Send the following JSON to POST /api/v1/decode with the server key. Use a returned transport value and an explicit context around the intended area.

{
  "transport_code": {
    "value": "!V5-ETCM",
    "profile": "E6"
  },
  "context": {
    "center": [
      11.575,
      48.137
    ],
    "radius_km": 20
  },
  "limit": 3,
  "offset": 0
}

Decode accepts exactly one of srl or transport_code. For transport reconstruction, context.center is WGS84 [longitude, latitude] and radius_km is 0–100. The profile can be inferred if omitted. limit is 1–20 (default 3); offset is 0–1000 (default 0).

The result includes transport_code and reconstruction: total and returned candidate counts, offset, limit, has_more and candidates. Each candidate has rank, Point geometry, distance_km and distance_to_next_best_km. There may be no match or several matches. Require application or operator resolution; do not silently treat the first candidate as an authoritative location.

Short-code precision_m describes approximate local grid scale. It is not sensor accuracy, a guaranteed reconstruction error or the required context radius. Read about Location Context.

Limits and errors

Rate values are provisional operational defaults, not purchased allowances or an SLA. Authorized invalid requests also consume quota. Application quotas are not a billing ledger. Responses use Cache-Control: no-store.

{
  "error": {
    "code": "API.ACCESS.INVALID_KEY",
    "message": "A valid confidential platform API key is required.",
    "category": "authorization",
    "details": {}
  }
}

Iframe limits and error events follow the Geometry Embed contract.

Versions and availability

Use the authenticated Server API v1 contract above. Legacy getsrl, getgeo and getproximities endpoints return 410; migrate to encode/decode. Existing /maps/api/v1/encode and /maps/api/v1/decode aliases use the same server contract and quota.

Ordinary map-session endpoints are internal UI interfaces. Account settings provides key management. Self-service billing, published OpenAPI and proximity queries remain separate work.

Higher-volume paid plans and pricing have not been set. View plans or contact us about your requirements.