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

queryModestring · enumOptional

Localization engine for this single-frame query. "vps-1" (default) is the fast standard engine (~2s). "vps-2" is a deep-search engine with up to 15% higher recall and improved accuracy, at higher latency (~3-4s). Ideal for offline or challenging scenes. Ignored by the multi-image query endpoint.

Default: vps-1Example: vps-2Possible values:

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: 5 · max: 100Optional

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

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, so [-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: 651

{
  "mapCode": "MAP-X2P23E7Q35VD",
  "mapSetCode": "MAPSET-ABC123",
  "queryMode": "vps-2",
  "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)

queryModestring · enumOptional

Localization engine for this single-frame query. "vps-1" (default) is the fast standard engine (~2s). "vps-2" is a deep-search engine with up to 15% higher recall and improved accuracy, at higher latency (~3-4s). Ideal for offline or challenging scenes. Ignored by the multi-image query endpoint.

Default: vps-1Example: vps-2Possible values:

imageTypestring · enumOptional

Projection of the uploaded queryImage. "pinhole" (default) is a standard perspective photo, and fx, fy, px, py, width and height are required with it. "equirect" is a full 360 equirectangular panorama: camera intrinsics are not required and are ignored if sent, and the returned pose describes the forward-looking view, meaning the direction the centre column of the image faces. Takes precedence over queryMode.

Default: pinholeExample: equirectPossible values:

isRightHandedstring · enumOptionalExample: truePossible values:

fxstringOptional

Focal length in x, in pixels. Required when imageType is pinhole, ignored when it is equirect.

Example: 669.535888671875

fystringOptional

Focal length in y, in pixels. Required when imageType is pinhole, ignored when it is equirect.

Example: 669.535888671875

pxstringOptional

Principal point x, in pixels. Required when imageType is pinhole, ignored when it is equirect.

Example: 478.8777160644531

pystringOptional

Principal point y, in pixels. Required when imageType is pinhole, ignored when it is equirect.

Example: 364.9244079589844

widthstringOptional

Image width in pixels. Required when imageType is pinhole, ignored when it is equirect.

Example: 960

heightstringOptional

Image height in pixels. Required when imageType is pinhole, ignored when it is equirect.

Example: 720

queryImagestring · binaryRequired

Image file for multipart requests. JPEG or PNG, 30 MB or smaller. For pinhole, resolution must not exceed 1280x1280. For equirect, width must be 2048 to 16384 px with an aspect ratio of at least 1.9:1 (a 2:1 panorama).

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

hintRadiusstring · min: 5 · max: 100Optional

Search radius in meters for spatial filtering (default 25m). Only applies when geoHint or hintPosition is provided. Range 5-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. Missing required fields (including fx, fy, px, py, width and height when imageType is pinhole), a pinhole image over 1280x1280, an equirect image outside 2048 to 16384 px width or below a 1.9:1 aspect ratio, an unreadable JPEG or PNG, or a file field not named queryImage.

application/json

401

Unauthorized

application/json

413

Payload too large. queryImage exceeds 30 MB.

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: 480

{
  "mapCode": "text",
  "mapSetCode": "text",
  "queryMode": "vps-2",
  "imageType": "equirect",
  "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.

Code Example (Python)

import json
import requests

BASE_URL = "https://api.multiset.ai/v1"
TOKEN = "YOUR_M2M_TOKEN"

with open("query.jpg", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/vps/map/query-form",
        headers={"Authorization": f"Bearer {TOKEN}"},
        data={
            "mapCode": "MAP_RJFKKWQ1787J",
            "isRightHanded": "false",
            "width": "720",
            "height": "960",
            "fx": "670.4620971679688",
            "fy": "670.4620971679688",
            "px": "478.838623046875",
            "py": "365.346618652343",
            # Optional localization hints, all as strings
            "hintPosition": "-3.452,0.252,-0.531",
            "hintRadius": "15",
            "hintFloorHeight": "[1.5, 4.5]",
        },
        files={"queryImage": ("query.jpg", f, "image/jpeg")},
    )

print(response.status_code, response.json())

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 5–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]"

Query Mode: queryMode

The queryMode parameter selects which localization engine runs your query, letting you trade latency for accuracy. The request and response format stay exactly the same on both engines.

Value	Engine	Description
vps-1	Standard (default)	The fast standard single-image localization engine, roughly 2 seconds. Best for real-time, interactive localization.
vps-2	Deep Search	A deep-search engine with up to 15% higher recall and improved accuracy, at higher latency (around 3 to 4 seconds). Best for offline or background workflows and challenging, visually repetitive scenes.

Rules:

• Optional. When omitted, the query runs on vps-1, so existing integrations are unaffected.

• Supported on both single-image endpoints: /vps/map/query (JSON) and /vps/map/query-form (form-data). It is ignored by the multi-image query endpoint.

• Can be combined with all localization parameters (hintPosition, hintRadius, hintFloorHeight, geoHint, hintMapCodes).

• Works with Maps, MapSets, and versioned maps.

Examples:

// JSON body: run this query on the Deep Search engine
"queryMode": "vps-2"

// Form-data endpoints: pass as a plain string field
"queryMode": "vps-2"

Use vps-2 when accuracy matters more than latency, for example when placing persistent content or localizing in repetitive corridors. For high-frequency relocalization during an AR session, vps-1 remains the recommended default. You can also try both engines on your own datasets from the Developer Portal simulation viewer. See Query Mode for guidance on choosing between the two.

Image Type: imageType

imageType tells the query which projection your image uses. It applies to /vps/map/query-form only.

Value	Image	Camera intrinsics
pinhole	A standard perspective photo (default)	Required. Send fx, fy, px, py, width, height.
equirect	A full 360° equirectangular panorama	Not required. Send them and they are ignored.

A pinhole query needs intrinsics before a pixel can become a direction. An equirectangular image carries that already, so there is nothing to send. You get back one pose: the pose of the forward-looking view, meaning the direction the centre column of the image faces.

Rules:

• Optional. When omitted the query runs as pinhole, so existing integrations are unaffected.

• equirect takes precedence over queryMode. Setting both is not an error, the queryMode value is simply not used.

• queryImage must be 2048 to 16384 px wide with an aspect ratio of at least 1.9:1, and 30 MB or smaller. Outside that, the request fails with 400, or 413 if it is only the file size.

• Works with Maps, MapSets, and versioned maps, and with all localization parameters.

• REST only. The Unity, Quest, iOS and Android SDKs capture perspective frames and do not expose imageType.

Example:

curl -X POST "$BASE_URL/v1/vps/map/query-form" \
  -H "Authorization: Bearer $TOKEN" \
  -F "imageType=equirect" \
  -F "mapCode=MAP_XXXXXXXXXXXX" \
  -F "isRightHanded=true" \
  -F "queryImage=@panorama.jpg"

The response has the same shape as a pinhole query: poseFound, position, rotation, confidence, and the matched mapIds and mapCodes. The rotation describes the forward-looking view, so orient your panorama with its centre column along your direction of travel if you want the returned heading to mean that. See Equirect Query.

Because one panorama covers the whole horizon, an equirect query does not depend on the user facing a mapped surface, which makes it a good fit for tripod, trolley, and robot captures. For a hand-held AR session, a pinhole frame from the device camera is still the right choice.

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.

Tracking poses are optional

The imageN_data parts are optional, which lets the multi-image query be used outside a SLAM session, for example from a set of stills or a camera rig with no tracking.

You send	What happens
A pose for every image	The poses are used. This is the most accurate option.
No poses at all	The images are matched against each other instead, so they must visually overlap. Slightly less accurate.
A pose for some images	Accepted, but treated as if you sent none. The poses you did send are not used, and the overlap requirement applies.

Two rules:

• Send a pose for every image, or for none. A partial set is not rejected, but it is no better than sending none, so it is worth making the choice explicit in your client.

• A pose that you do send must be complete. All seven fields (x, y, z, qx, qy, qz, qw) must be present together, and the value must be valid JSON. Either problem fails with 400.

The trackingPose in the response is your input echoed back, so it is absent whenever the poses were not used.

Multi-image query for a VPS map or map set

post

Performs a query using several uploaded images, along with camera intrinsics and a map or map-set identifier. Requires a minimum of 4 images and accepts a maximum of 6 in a single request.

The request is multipart/form-data. The image binaries are sent as file parts named image1 to image6, and every other field, including each imageN_data tracking pose, is sent as a plain text part. The imageN_data parts are optional: send a tracking pose for every image, or for none of them. Sending a pose that is missing some of its seven fields fails with 400.

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

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

hintRadiusstring · min: 5 · max: 100Optional

Search radius in meters for spatial filtering (default 25m). Only applies when geoHint or hintPosition is provided. Range 5-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

Optional JSON-encoded tracking pose for image1, from your local SLAM session (position x, y, z and rotation qx, qy, qz, qw). Send a pose for every image, or for none. Sending one for only some images is accepted but the poses are then not used, and the images must visually overlap each other, exactly as if you had sent none. A pose you do send must carry all seven fields and be valid JSON, or the request fails with 400.

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. Missing required fields, an image over 1280x1280, an unreadable JPEG or PNG, or an imageN_data tracking pose that is incomplete or not valid JSON.

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,
  "frames": [
    {
      "imageId": "image1",
      "poseFound": true,
      "position": {
        "x": 3.840479122718551,
        "y": 2.235871409437739,
        "z": 7.531184729001473
      },
      "rotation": {
        "x": 0.0104227310558921,
        "y": 0.7218904471209736,
        "z": -0.0248105549134402,
        "w": 0.6914338805274115
      },
      "confidence": 0.2988120487183476
    },
    {
      "imageId": "image2",
      "poseFound": true,
      "position": {
        "x": 3.8697402118840367,
        "y": 2.228145503710395,
        "z": 7.601552884101918
      },
      "rotation": {
        "x": 0.0061140925713855,
        "y": 0.7331886201553348,
        "z": -0.0235510983247741,
        "w": 0.6795726114402537
      },
      "confidence": 0.31204558839107516
    },
    {
      "imageId": "image3",
      "poseFound": false
    },
    {
      "imageId": "image4",
      "poseFound": true,
      "position": {
        "x": 3.9023228363353613,
        "y": 2.2199969114542415,
        "z": 7.684019738005462
      },
      "rotation": {
        "x": 0.0008889080606250241,
        "y": 0.7454695784085924,
        "z": -0.022682644709609446,
        "w": 0.6661529967948453
      },
      "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,
    "frames": [
        {
            "imageId": "image1",
            "poseFound": true,
            "position": {
                "x": 3.8404791227185512,
                "y": 2.2358714094377391,
                "z": 7.5311847290014732
            },
            "rotation": {
                "x": 0.0104227310558921,
                "y": 0.7218904471209736,
                "z": -0.0248105549134402,
                "w": 0.6914338805274115
            },
            "confidence": 0.29881204871834762
        },
        {
            "imageId": "image2",
            "poseFound": true,
            "position": {
                "x": 3.8697402118840365,
                "y": 2.2281455037103951,
                "z": 7.6015528841019182
            },
            "rotation": {
                "x": 0.0061140925713855,
                "y": 0.7331886201553348,
                "z": -0.0235510983247741,
                "w": 0.6795726114402537
            },
            "confidence": 0.31204558839107514
        },
        {
            "imageId": "image3",
            "poseFound": false
        },
        {
            "imageId": "image4",
            "poseFound": true,
            "position": {
                "x": 3.9023228363353613,
                "y": 2.2199969114542415,
                "z": 7.684019738005462
            },
            "rotation": {
                "x": 0.0008889080606250241,
                "y": 0.7454695784085924,
                "z": -0.022682644709609446,
                "w": 0.6661529967948453
            },
            "confidence": 0.34274043817304123
        }
    ],
    "mapCodes": ["MAP_RJFKKWQ1787J"],
    "responseTime": 4919
}

Per-image poses (frames)

Alongside the single estimatedPose, the response carries a frames array with one entry per image you sent, in the order the images were numbered. Each entry reports whether that individual image localized on its own, and if it did, the 6-DoF pose computed from it.

Field	Type	Description
imageId	string	Which image this entry describes (image1 to image6), matching the file part you uploaded.
poseFound	boolean	Whether this individual image produced a pose.
position	object	x, y, z in map-local coordinates. Present only when poseFound is true.
rotation	object	Quaternion x, y, z, w. Present only when poseFound is true.
confidence	number	Confidence score for this image alone. May be absent on a frame that did not localize.

How frames relates to the top-level pose:

• estimatedPose remains the answer to use. It is the consensus pose across all images and is more robust than any single frame.

• The top-level imageId names the winning frame, so the entry with that imageId carries the same position, rotation, and confidence as estimatedPose.

• Every pose in frames is in the same coordinate frame as estimatedPose: it follows the isRightHanded value you sent, and on a versioned map it is expressed in the base map's frame.

• Individual frames can fail while the overall query succeeds. A frame with "poseFound": false has no position or rotation, which is normal when one image in the set is blurred, occluded, or pointed at a featureless surface.

• frames is informational. It is useful for diagnosing capture quality, spotting outlier viewpoints, and understanding which frames drove the result, but you do not need it for standard localization.

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.

Code Example (Python)

Split the request in two parts: the image binaries go in files, and every other field, including each imageN_data tracking pose, goes in data as a string.

import json
import requests
from contextlib import ExitStack

BASE_URL = "https://api.multiset.ai/v1"
TOKEN = "YOUR_M2M_TOKEN"

image_paths = ["image1.jpg", "image2.jpg", "image3.jpg", "image4.jpg"]

# Local SLAM tracking pose (ARKit / ARCore) for each image, in the same order
tracking_poses = [
    {"x": -5.1772, "y": 0.2936, "z": -2.6439, "qx": -0.0185, "qy": 0.9949, "qz": -0.0691, "qw": 0.0703},
    {"x": -4.8210, "y": 0.3011, "z": -2.1094, "qx": -0.0201, "qy": 0.9932, "qz": -0.0805, "qw": 0.0812},
    {"x": -4.3945, "y": 0.2874, "z": -1.7723, "qx": -0.0173, "qy": 0.9951, "qz": -0.0664, "qw": 0.0699},
    {"x": -3.9012, "y": 0.2952, "z": -1.3388, "qx": -0.0190, "qy": 0.9940, "qz": -0.0731, "qw": 0.0764},
]

# Text fields, all sent as strings
text_fields = {
    "mapCode": "MAP_RJFKKWQ1787J",   # or "mapSetCode", exactly one of the two
    "isRightHanded": "false",
    "width": "720",
    "height": "960",
    "fx": "670.4620971679688",
    "fy": "670.4620971679688",
    "px": "478.838623046875",
    "py": "365.346618652343",
    # Optional localization hints
    "hintPosition": "-3.452,0.252,-0.531",
}

# Each imageN file part needs a matching imageN_data text part
for index, pose in enumerate(tracking_poses, start=1):
    text_fields[f"image{index}_data"] = json.dumps(pose)

with ExitStack() as stack:
    files = [
        (
            f"image{index}",
            (f"image{index}.jpg", stack.enter_context(open(path, "rb")), "image/jpeg"),
        )
        for index, path in enumerate(image_paths, start=1)
    ]

    response = requests.post(
        f"{BASE_URL}/vps/map/multi-image-query",
        headers={"Authorization": f"Bearer {TOKEN}"},
        data=text_fields,
        files=files,
    )

print(response.status_code, response.json())

Rules for the multipart body:

• File parts must be named image1 to image6, and each one needs a matching imageN_data text part with the same number. A missing imageN_data returns 400 with Missing metadata for imageN.

• Each imageN_data value is a JSON-encoded string containing x, y, z, qx, qy, qz and qw. All seven keys are required.

• Send between 4 and 6 images. Fewer returns At least 4 image file is required!, more returns Maximum 6 image files allowed!.

• Pass exactly one of mapCode or mapSetCode.

• Do not set the Content-Type header yourself. requests adds multipart/form-data with the boundary when you pass files.