# GeoHint in Localization

Release **v1.7.0** adds two major features to the MultiSet VPS for improved localization in large georeferenced maps.

1. **GeoHint in Localization Requests**
   * **Purpose:** Pass the device's GPS coordinates (latitude, longitude, altitude) in localization requests after georeferencing your map.
   * **Benefits:**
     * Significantly reduces localization time in large outdoor environments.
     * Mitigates issues of visual aliasing.
     * Improves overall localization performance and accuracy.
2. **GeoCoordinates in Localization Responses**
   * **Purpose:** Get localization results directly in global GPS coordinates (latitude, longitude, altitude).
   * **Benefits:**
     * Enables seamless integration with other applications or services that rely on GPS coordinates.
     * Directly connects localization results to real-world locations.

***

### How to Use These Features

#### In Unity (MultiSet SDK Manager)

The following GPS-related options are available in the MultiSet SDK Manager component in Unity:

* **passGeoPose:** Enables sending device GPS as a GeoHint in requests.
* **geoCoordinatesInResponse:** Enables receiving localization results in global GPS coordinates.
* **hintRadius:** Search radius in meters for spatial filtering (default: 25m, range: 1–100). Only applies when geoHint or hintPosition is provided.
* **use2DFiltering:** When enabled, skips altitude (Y-axis) in geoHint spatial filtering and uses only horizontal distance (X and Z axes). Only applies when geoHint is provided.

**Setup Steps:**

1. **Update Map GeoCoordinates:**\
   Before enabling these features, update the geo-coordinates of your map in the MultiSet Developer Portal.
2. **Enable Options in Unity:**
   * Open your scene and select the MultiSet SDK Manager (or Single Frame Localization Manager).
   * Check the box for `Pass GeoPose` to send device GPS as a hint.
   * Check the box for `GeoCoordinates In Response` to receive results in global GPS coordinates.
   * Adjust `Hint Radius` to control the spatial filtering search radius (default: 25 meters).
   * Enable `Use 2D Filtering` if you want to ignore altitude differences during spatial filtering.

## GeoHint for MapSet

To enable GeoHint in MapSet, start by georeferencing the primary map. Afterward, merge all the maps to enable georeferencing for the entire MapSet.

***

#### Using MultiSet Localization API Directly

If you are integrating via the API (outside Unity), you can enable these features by including the following fields in your localization request:

**Request Parameters**

| Field                     | Type   | Description                                                                                                     |
| ------------------------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| `geoHint`                 | string | Comma-separated string, e.g. `"latitude,longitude,altitude"`. Pass the device's GPS as a hint for localization. |
| `convertToGeoCoordinates` | string | Pass `"true"` to receive localization response in global coordinates.                                           |

**Example Request Body and Response:**

JSON

<pre><code>{
  "mapId": "your-map-id",
  "geoHint": "37.4219983,-122.084,10.5",
  "convertToGeoCoordinates": "true",
  "isRightHanded": "false",
  ..... /other parameters
<strong>}
</strong></code></pre>

```
{
    "poseFound": true,
    "position": {
        "x": -0.12362211813361121,
        "y": 1.563005737034826,
        "z": 6.99455530632896
    },
    "rotation": {
        "x": 0.0054829774148128785,
        "y": -0.575302195022844,
        "z": -0.009251237126862318,
        "w": 0.8178702439703922
    },
    "mapIds": [
        "68c8fe2ff8f229955c39eb02"
    ],
    "GeoPose": {
        "frame_spec": {
            "model": "WGS-84",
            "frame": "Y-Up-ENU"
        },
        "pose": {
            "position": {
                "lat": 12.952603117267845,
                "lon": 77.61615745357129,
                "h": 912.923009573482
            },
            "quaternion": {
                "x": 0.01041866301787597,
                "y": -0.985121678974319,
                "z": -0.002664561995662227,
                "w": 0.1715215123100019
            }
        }
    }
}
```

### Feature Details

#### 1. Passing GeoHint in Localization

* **How:**\
  When `passGeoPose` is enabled, the SDK will automatically attach the device's current GPS coordinates to your localization request.
* **Why:**\
  This narrows down the search area in large outdoor georeferenced maps, speeding up localization and reducing errors.

#### 2. Receiving GeoCoordinates in Response

* **How:**\
  When `geoCoordinatesInResponse` is enabled (or when `convertToGeoCoordinates: "true"` is included in API requests), the SDK converts the localization result into global GPS coordinates.
* **Why:**\
  This is useful for interoperability with external systems or for mapping localization results to real-world positions.

***

### Important Notes

* **Map Preparation:**\
  Ensure your map is properly geo-referenced and updated in the MultiSet Developer Portal before using these options.
* **Platform Support:**\
  GPS functionality requires device location permissions; the SDK will prompt the user accordingly.
* **Unity Integration:**\
  No additional scripting is needed—just enable the options in the SDK Manager.

***


---

# Agent Instructions: 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:

```
GET https://docs.multiset.ai/basics/localization/geohint-in-localization.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.