> For the complete documentation index, see [llms.txt](https://multiset.gitbook.io/multiset/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://multiset.gitbook.io/multiset/basics/rest-api-docs/map-query.md).

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

{% hint style="warning" %}
The maximum query image resolution is **1280** pixels in either width or height.
{% endhint %}

{% openapi src="/files/ajrrlVmhtUvgT9mQ0Qyq" path="/vps/map/query" method="post" %}
[VPSquery.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-406eb157fff5fb139aaee6a1cd94b8c29869a724%2FVPSquery.yaml?alt=media\&token=1135cd98-90aa-44ae-b601-00aa1dcd4c96)
{% endopenapi %}

#### Sample Response (JSON Body)

```json
{
    "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
}
```

{% openapi src="/files/4THolmFT4ct9qovYeocP" path="/vps/map/query-form" method="post" %}
[VPSqueryform.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-34198e2819cdef492186cdaeab20ff12f2032529%2FVPSqueryform.yaml?alt=media\&token=5b183c73-7b86-4619-8aab-6e258a4def2b)
{% endopenapi %}

#### Sample Response (Form Data)

```json
{
    "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
}
```

{% hint style="warning" %}
**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.
{% endhint %}

### 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`)                 |

{% hint style="warning" %}
**`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.
{% endhint %}

On form-data endpoints, pass `hintPosition` as a JSON-encoded string, e.g. `"[2.5, 0.1, 8.0]"`. See [Pose Prior : HintPosition](/multiset/basics/localization/pose-prior-hintposition.md) 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:**

```json
// 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.

{% hint style="info" %}
**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.
{% endhint %}

{% openapi src="/files/oOKFI0YnlAkR5K578gJk" path="/vps/map/multi-image-query" method="post" %}
[vps-maps-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-5339be58d4cf59843f518b3a4dac6507715f74f0%2Fvps-maps-api.yaml?alt=media)
{% endopenapi %}

#### Sample Response (Multi Image)

```json
{
    "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
}
```

{% hint style="warning" %}
**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.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://multiset.gitbook.io/multiset/basics/rest-api-docs/map-query.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.