# 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="<https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-483b8b866b185ccbcfc3a5eff92c4af3aec702d5%2FVPSquery.yaml?alt=media>" 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-483b8b866b185ccbcfc3a5eff92c4af3aec702d5%2FVPSquery.yaml?alt=media)
{% 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="<https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-3b187f9fe3eb8def642a249a800355164f801e9e%2FVPSqueryform.yaml?alt=media>" 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-3b187f9fe3eb8def642a249a800355164f801e9e%2FVPSqueryform.yaml?alt=media)
{% 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 %}

### 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="<https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-a36eab129f933a781198644018a89f24fcc7131c%2Fvps-maps-api.yaml?alt=media>" 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-a36eab129f933a781198644018a89f24fcc7131c%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 %}