Map Query

VPS Query API

Query your map to get the device position with respect to Map local origin. The query API takes query image (encoded as base64 string) and other image metadata.

The maximum query image resolution is 1280 pixels in either width or height.

Query a VPS map with specific parameters

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

mapCodestringOptional

Code to identify the VPS map (required if mapSetCode is not provided)

Example: MAP-X2P23E7Q35VD

mapSetCodestringOptional

Code to identify the map set (required if mapCode is not provided)

Example: MAPSET-ABC123

hintMapCodesstring[]Optional

List of map codes for spatial hints (only valid with mapSetCode)

Example: ["MAP-X2P23E7Q35VD","MAP-Y3Q34F8R46WE"]

hintPositionnumber[]Optional

Position hint [x, y, z] for spatial filtering. Must be in the map's left-handed (LHS / Unity) coordinate system — the same frame as the position field in a successful localization response (isRightHanded=false).

Example: [2.5,0.1,8]

geoHintnumber[]Optional

Geographic hint [latitude, longitude, altitude] - converts to local hintPosition

Example: [37.7749,-122.4194,10]

hintRadiusnumber · min: 1 · max: 100Optional

Search radius in meters for spatial filtering (default 25m). Only applies when geoHint or hintPosition is provided.

Example: 25

use2DFilteringbooleanOptional

When true, skip altitude (Y-axis) in geoHint spatial filtering, using only horizontal distance (X and Z axes). Only applies when geoHint is provided.

Default: falseExample: false

hintFloorHeightnumber[] · min: 2 · max: 2Optional

Floor height band [y_min, y_max] in map-local coordinates. Search run within this vertical range. Works for both single Map and MapSet (positions are in global/MapSet coordinate space). Order does not matter — [-3, -1] and [-1, -3] both select y ∈ [-3, -1].

Example: [1.5,4.5]

convertToGeoCoordinatesbooleanOptional

Convert result to geographic coordinates (adds GeoPose to response)

Example: false

isRightHandedbooleanOptional

Flag to indicate if response pose is in right-handed coordinate system

Example: false

queryImagestring · base64Required

Base64 encoded image data

Example:

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA8AAAALQCAIAAADQFY7jAAAgAElEQVR4AaS9+5NdR5Lfh34BjW4AxJMgOTN8zCw5OzHriV2vvFrZDjtCVki2Xt5VaKVdybLClsL+3xz23+DQr9ZPlmO16xmvh

Responses

200

Query successful

application/json

poseFoundbooleanRequired

Indicates if the pose was successfully found

Example: true

confidencenumberRequired

Confidence score of the pose estimation

Example: 0.46875

mapIdsstring[]Optional

Array of matched map IDs

Example: ["67e12d4bff7ecf561f2f8a0c"]

mapCodesstring[]Optional

Array of matched map codes

Example: ["MAP_RJFKKWQ1787J"]

responseTimenumberOptional

Response time in milliseconds

Example: 2572

400

Bad request

application/json

401

Unauthorized

application/json

post

/vps/map/query

POST /v1/vps/map/query HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 631

{
  "mapCode": "MAP-X2P23E7Q35VD",
  "mapSetCode": "MAPSET-ABC123",
  "hintMapCodes": [
    "MAP-X2P23E7Q35VD",
    "MAP-Y3Q34F8R46WE"
  ],
  "hintPosition": [
    2.5,
    0.1,
    8
  ],
  "geoHint": [
    37.7749,
    -122.4194,
    10
  ],
  "hintRadius": 25,
  "use2DFiltering": false,
  "hintFloorHeight": [
    1.5,
    4.5
  ],
  "convertToGeoCoordinates": false,
  "cameraIntrinsics": {
    "fx": 664.3856201171875,
    "fy": 664.3856201171875,
    "px": 478.9782409667969,
    "py": 364.9932861328125
  },
  "isRightHanded": false,
  "resolution": {
    "width": 960,
    "height": 720
  },
  "queryImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA8AAAALQCAIAAADQFY7jAAAgAElEQVR4AaS9+5NdR5Lfh34BjW4AxJMgOTN8zCw5OzHriV2vvFrZDjtCVki2Xt5VaKVdybLClsL+3xz23+DQr9ZPlmO16xmvh"
}

{
  "poseFound": true,
  "position": {
    "x": -5.89516855615433,
    "y": 1.225031596452081,
    "z": 2.2112895596804227
  },
  "rotation": {
    "x": -0.007873432249486393,
    "y": 0.8212519784928444,
    "z": 0.03204363652415735,
    "w": 0.5696107462509017
  },
  "confidence": 0.46875,
  "mapIds": [
    "67e12d4bff7ecf561f2f8a0c"
  ],
  "mapCodes": [
    "MAP_RJFKKWQ1787J"
  ],
  "responseTime": 2572
}

Sample Response (JSON Body)

{
    "poseFound": true,
    "position": {
        "x": -5.89516855615433,
        "y": 1.225031596452081,
        "z": 2.2112895596804227
    },
    "rotation": {
        "x": -0.007873432249486393,
        "y": 0.8212519784928444,
        "z": 0.03204363652415735,
        "w": 0.5696107462509017
    },
    "confidence": 0.46875,
    "mapIds": ["67e12d4bff7ecf561f2f8a0c"],
    "mapCodes": ["MAP_RJFKKWQ1787J"],
    "responseTime": 2572
}

Query a VPS map or mapset using form-data

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

mapCodestringOptional

The map code for the map to query (required if mapSetCode is not provided)

mapSetCodestringOptional

The map set code for the map set to query (required if mapCode is not provided)

isRightHandedstring · enumOptionalExample: truePossible values:

fxstringRequiredExample: 669.535888671875

fystringRequiredExample: 669.535888671875

pxstringRequiredExample: 478.8777160644531

pystringRequiredExample: 364.9244079589844

widthstringRequiredExample: 960

heightstringRequiredExample: 720

queryImagestring · binaryRequired

Image file for multipart requests

convertToGeoCoordinatesstring · enumOptional

Convert result to geographic coordinates

Example: falsePossible values:

hintMapCodesstring[]Optional

List of map codes for hints (only valid with mapSetCode)

Example: ["MAP-X2P23E7Q35VD","MAP-Y3Q34F8R46WE"]

hintPositionstringOptional

Position hint "x,y,z" (comma-separated string). Must be in the map's left-handed (LHS / Unity) coordinate system — the same frame as the position field in a successful localization response (isRightHanded=false).

Example: 2.5,0.1,8.0

geoHintstringOptional

Geographic hint "latitude,longitude,altitude" (comma-separated)

Example: 37.7749,-122.4194,10.0

hintRadiusstringOptional

Search radius in meters for spatial filtering (default 25m). Only applies when geoHint or hintPosition is provided. Range 1-100.

Example: 25

use2DFilteringstring · enumOptional

When true, skip altitude (Y-axis) in geoHint spatial filtering. Only applies when geoHint is provided.

Example: falsePossible values:

hintFloorHeightstringOptional

JSON-encoded floor height band "[y_min, y_max]" in map-local coordinates. Search run within this vertical range. Order does not matter.

Example: [1.5, 4.5]

Responses

200

Query successful

application/json

poseFoundbooleanOptional

Indicates if the pose was successfully found

confidencenumberOptional

mapIdsstring[]Optional

mapCodesstring[]Optional

responseTimenumberOptional

400

Bad request

application/json

401

Unauthorized

application/json

post

/vps/map/query-form

POST /v1/vps/map/query-form HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 437

{
  "mapCode": "text",
  "mapSetCode": "text",
  "isRightHanded": "true",
  "fx": "669.535888671875",
  "fy": "669.535888671875",
  "px": "478.8777160644531",
  "py": "364.9244079589844",
  "width": "960",
  "height": "720",
  "queryImage": "binary",
  "convertToGeoCoordinates": "false",
  "hintMapCodes": [
    "MAP-X2P23E7Q35VD",
    "MAP-Y3Q34F8R46WE"
  ],
  "hintPosition": "2.5,0.1,8.0",
  "geoHint": "37.7749,-122.4194,10.0",
  "hintRadius": "25",
  "use2DFiltering": "false",
  "hintFloorHeight": "[1.5, 4.5]"
}

{
  "poseFound": true,
  "position": {
    "x": -2.8765866867008025,
    "y": 1.4018881843419664,
    "z": 7.677072632098843
  },
  "rotation": {
    "x": -0.0033476528966347096,
    "y": 0.6750939967230872,
    "z": -0.00310829178339555,
    "w": 0.7377175796541121
  },
  "confidence": 0.9175769612711023,
  "mapIds": [
    "67e12d4bff7ecf561f2f8a0c"
  ],
  "mapCodes": [
    "MAP_RJFKKWQ1787J"
  ],
  "responseTime": 2669
}

Sample Response (Form Data)

{
    "poseFound": true,
    "position": {
        "x": -2.8765866867008025,
        "y": 1.4018881843419664,
        "z": 7.677072632098843
    },
    "rotation": {
        "x": -0.0033476528966347096,
        "y": 0.6750939967230872,
        "z": -0.00310829178339555,
        "w": 0.7377175796541121
    },
    "confidence": 0.9175769612711023,
    "mapIds": ["67e12d4bff7ecf561f2f8a0c"],
    "mapCodes": ["MAP_RJFKKWQ1787J"],
    "responseTime": 2669
}

FormData Content-Type: When using fetch or similar HTTP clients with FormData, do not manually set the Content-Type header. The browser automatically sets it to multipart/form-data with the required boundary string. Manually setting it will strip the boundary and cause a parse error.

Spatial Hint: hintPosition

The hintPosition parameter restricts the localization search to a radius around a given point in the map, speeding up the query and improving accuracy in visually repetitive scenes.

Parameter

Type

Description

hintPosition

[x, y, z]

Hint point in the map's left-handed (LHS / Unity) coordinate system

hintRadius

number

Search radius in meters (default 25, range 1–100)

hintPosition is in LHS (Unity) coordinates — the same coordinate system returned in the position field of a successful localization response (isRightHanded: false). A previous localization result's position can be passed directly as the hint. If your application works in right-handed space (e.g. ROS, Three.js), convert to LHS before sending.

On form-data endpoints, pass hintPosition as a JSON-encoded string, e.g. "[2.5, 0.1, 8.0]". See Pose Prior : HintPosition for the full guide.

Floor-Level Search: hintFloorHeight

The hintFloorHeight parameter limits the search to a specific vertical band, enabling floor-level localization in multi-floor buildings.

Parameter

Type

Description

hintFloorHeight

[y_min, y_max]

Vertical band in map-local Y coordinates

Rules:

Both values are in map-local coordinates (or global MapSet coordinates for MapSet queries)
Order does not matter — [-3, -1] and [-1, -3] both select images with y ∈ [-3, -1]
Can be combined with hintPosition — spatial filter runs first, height filter applies on the result

Examples:

// Floor 2 of a building where floor is at y=3.0, ceiling at y=6.0
"hintFloorHeight": [3.0, 6.0]

// Basement (negative Y)
"hintFloorHeight": [-3.0, -0.5]

// Form-data endpoints — pass as JSON string
"hintFloorHeight": "[1.5, 4.5]"

VPS Multi Image Query API

Multi-image query API requires a minimum of 4 images in each request. Up to 6 images can be passed. Higher image counts increase localization robustness and accuracy but may compromise latency.

About image#_data properties: The image1_data, image2_data, etc. fields contain the local SLAM tracking data (position and rotation) for when each image was captured. This is the device pose in the local coordinate system from ARKit (iOS) or ARCore (Android) at the moment the image was taken.

Multi-image query for a VPS map or map set

post

Performs a query using one or more uploaded images, along with camera intrinsics and optional map or map-set identifiers. Supports up to four images in a single request.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

isRightHandedstring · enumOptional

Specifies whether the coordinate system is right-handed. Because this is form-data, it's sent as a string ("true" or "false").

Example: truePossible values:

widthstringRequired

The width (in pixels) of the input image(s).

Example: 960

heightstringRequired

The height (in pixels) of the input image(s).

Example: 720

pxstringRequired

The principal point x-coordinate.

Example: 478.838623046875

pystringRequired

The principal point y-coordinate.

Example: 365.346618652343

fxstringRequired

The focal length along x-axis.

Example: 670.4620971679688

fystringRequired

The focal length along y-axis.

Example: 670.4620971679688

mapCodestringOptional

Code to identify the map (required if mapSetCode is not provided).

mapSetCodestringOptional

A code to identify the map set.

convertToGeoCoordinatesstring · enumOptional

Convert result to geographic coordinates

Example: falsePossible values:

hintMapCodesstring[]Optional

List of map codes for hints (only valid with mapSetCode)

Example: ["MAP-X2P23E7Q35VD","MAP-Y3Q34F8R46WE"]

hintPositionstringOptional

Example: 2.5,0.1,8.0

geoHintstringOptional

Geographic hint "latitude,longitude,altitude" (comma-separated)

Example: 37.7749,-122.4194,10.0

hintRadiusstringOptional

Search radius in meters for spatial filtering (default 25m). Only applies when geoHint or hintPosition is provided. Range 1-100.

Example: 25

use2DFilteringstring · enumOptional

When true, skip altitude (Y-axis) in geoHint spatial filtering. Only applies when geoHint is provided.

Example: falsePossible values:

hintFloorHeightstringOptional

JSON-encoded floor height band "[y_min, y_max]" in map-local coordinates. Search run within this vertical range. Order does not matter.

Example: [1.5, 4.5]

image1string · binaryRequired

The first image file to be uploaded.

image1_datastringOptional

JSON-encoded metadata for image1 (e.g., position and rotation).

Example: {"x":-5.1772,"y":0.2936,"z":-2.6439,"qx":-0.0185,"qy":0.9949,"qz":-0.0691,"qw":0.0703}

image2string · binaryOptional

The second image file to be uploaded.

image2_datastringOptional

JSON-encoded metadata for image2.

Example: {"x":-3.12,"y":1.01,"z":2.56,"qx":0.0,"qy":0.707,"qz":0.0,"qw":0.707}

image3string · binaryOptional

The third image file to be uploaded.

image3_datastringOptional

JSON-encoded metadata for image3.

Example: {"x":1.23,"y":-0.56,"z":5.0,"qx":-0.0185,"qy":0.9949,"qz":-0.0691,"qw":0.0703}

image4string · binaryOptional

The fourth image file to be uploaded.

image4_datastringOptional

JSON-encoded metadata for image4.

Example: {"x":10.0,"y":-2.0,"z":0.0,"qx":0.0,"qy":1.0,"qz":0.0,"qw":0.0}

Responses

200

Query successful

application/json

poseFoundbooleanOptional

imageIdstringOptional

mapIdsstring[]Optional

confidencenumberOptional

mapCodesstring[]Optional

responseTimenumberOptional

400

Bad request

application/json

401

Unauthorized - Missing or invalid token

application/json

404

Map/MapSet not found (if applicable)

application/json

500

Internal server error

application/json

post

/vps/map/multi-image-query

POST /v1/vps/map/multi-image-query HTTP/1.1
Host: api.multiset.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 899

{
  "isRightHanded": "true",
  "width": "960",
  "height": "720",
  "px": "478.838623046875",
  "py": "365.346618652343",
  "fx": "670.4620971679688",
  "fy": "670.4620971679688",
  "mapCode": "",
  "mapSetCode": "",
  "convertToGeoCoordinates": "false",
  "hintMapCodes": [
    "MAP-X2P23E7Q35VD",
    "MAP-Y3Q34F8R46WE"
  ],
  "hintPosition": "2.5,0.1,8.0",
  "geoHint": "37.7749,-122.4194,10.0",
  "hintRadius": "25",
  "use2DFiltering": "false",
  "hintFloorHeight": "[1.5, 4.5]",
  "image1": "binary",
  "image1_data": "{\"x\":-5.1772,\"y\":0.2936,\"z\":-2.6439,\"qx\":-0.0185,\"qy\":0.9949,\"qz\":-0.0691,\"qw\":0.0703}",
  "image2": "binary",
  "image2_data": "{\"x\":-3.12,\"y\":1.01,\"z\":2.56,\"qx\":0.0,\"qy\":0.707,\"qz\":0.0,\"qw\":0.707}",
  "image3": "binary",
  "image3_data": "{\"x\":1.23,\"y\":-0.56,\"z\":5.0,\"qx\":-0.0185,\"qy\":0.9949,\"qz\":-0.0691,\"qw\":0.0703}",
  "image4": "binary",
  "image4_data": "{\"x\":10.0,\"y\":-2.0,\"z\":0.0,\"qx\":0.0,\"qy\":1.0,\"qz\":0.0,\"qw\":0.0}"
}

{
  "poseFound": true,
  "estimatedPose": {
    "position": {
      "x": 3.9023228363353613,
      "y": 2.2199969114542415,
      "z": 7.684019738005462
    },
    "rotation": {
      "x": 0.0008889080606250241,
      "y": 0.7454695784085924,
      "z": -0.022682644709609446,
      "w": 0.6661529967948453
    }
  },
  "trackingPose": {
    "position": {
      "x": 0.0022450201213359833,
      "y": 2.471872329711914,
      "z": -10.018059730529785
    },
    "rotation": {
      "x": 0.030655404552817345,
      "y": 0.14812710881233215,
      "z": -0.00305502163246274,
      "w": -0.9884883761405945
    }
  },
  "imageId": "image4",
  "mapIds": [
    "67e12d4bff7ecf561f2f8a0c"
  ],
  "confidence": 0.34274043817304123,
  "mapCodes": [
    "MAP_RJFKKWQ1787J"
  ],
  "responseTime": 4919
}

Sample Response (Multi Image)

{
    "poseFound": true,
    "estimatedPose": {
        "position": {
            "x": 3.9023228363353613,
            "y": 2.2199969114542415,
            "z": 7.684019738005462
        },
        "rotation": {
            "x": 0.0008889080606250241,
            "y": 0.7454695784085924,
            "z": -0.022682644709609446,
            "w": 0.6661529967948453
        }
    },
    "trackingPose": {
        "position": {
            "x": 0.0022450201213359833,
            "y": 2.471872329711914,
            "z": -10.018059730529785
        },
        "rotation": {
            "x": 0.030655404552817345,
            "y": 0.14812710881233215,
            "z": -0.00305502163246274,
            "w": -0.9884883761405945
        }
    },
    "imageId": "image4",
    "mapIds": ["67e12d4bff7ecf561f2f8a0c"],
    "confidence": 0.34274043817304123,
    "mapCodes": ["MAP_RJFKKWQ1787J"],
    "responseTime": 4919
}

PreviousAuthentication NextMap Operations

Last updated 21 days ago

Was this helpful?