> For the complete documentation index, see [llms.txt](https://docs.multiset.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.multiset.ai/fundamentals/rest-api-docs/oscp-geopose.md). # OSCP GeoPose Protocol Localize against MultiSet maps using Open AR Cloud's GeoPose Protocol, so an OSCP client needs no MultiSet-specific code. ## Overview `POST /v1/vps/map/geopose` speaks [Open AR Cloud's GeoPose Protocol](https://github.com/OpenArCloud/oscp-geopose-protocol). An OSCP client can point at MultiSet and localize without knowing anything MultiSet-specific. It answers with the same localization quality as [Map Query](/fundamentals/rest-api-docs/map-query.md), and meters against your plan the same way. What differs is the shape of the request and the response. {% hint style="info" %} If you are building on MultiSet directly, use [Map Query](/fundamentals/rest-api-docs/map-query.md). This endpoint exists for interoperability: use it when you already have an OSCP client, or when you need to be one of several interchangeable providers behind a standard interface. {% endhint %} Not to be confused with [GeoPose Support](/fundamentals/localization/geopose-support.md), which describes the GeoPose **object** returned inside a normal MultiSet localization response. That is a field on an existing API. This is a separate endpoint speaking the full protocol. ## Protocol versions Versions **1.0** and **2.0** are both accepted, and the two are detected by the shape of the request: | Version | `sensorReadings` | Camera intrinsics | | ------- | ---------------------- | ----------------- | | **1.0** | Flat array | On the `Sensor` | | **2.0** | Object of typed arrays | On the reading | The version travels in the `Accept` header and is echoed in the response `Content-Type`: ``` Accept: application/vnd.oscp+json;version=2.0 ``` It defaults to `2.0` when the header is absent. An unrecognised version is a `400`. ## Choosing which map to query The GeoPose spec's body carries no map field, so there are two ways to scope a request. | Approach | How | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **By coordinate** (spec-native) | Include a `geolocationReading`. The nearest map whose [geo-fence](/fundamentals/georeferencing-maps/geo-fence.md) is in range is resolved and queried. | | **Explicitly** (MultiSet extension) | Pass `mapCode` or `mapSetCode` as a query parameter. | The query parameters take precedence over any `geolocationReading`. `mapCode` and `mapSetCode` are mutually exclusive. {% hint style="warning" %} Scoping by coordinate needs a geo-fence. Only active maps with `geoFenceReady: true` are considered, so a map that has never been geo-referenced is invisible to this route. See [Geo-fence](/fundamentals/georeferencing-maps/geo-fence.md). {% endhint %} ## The endpoint {% openapi src="/files/WYAZJL5j45Ad224Eqno9" path="/vps/map/geopose" method="post" %} [oscp-geopose-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-ddf91ad999edac0ee1172977024808f3e0ebe8d8%2Foscp-geopose-api.yaml?alt=media) {% endopenapi %} ## Image requirements Images must be **upright and non-mirrored**. Send `imageOrientation` with `rotation: 0` and `mirrored: false`, or rotate the image before encoding it. This matches the requirement on the native query API. A rotated or mirrored frame does not fail loudly, it simply fails to localize, so it is worth asserting in your client rather than discovering in the field. ## When no pose is found A request that cannot be localized returns a `404` with a `reason`. The one worth handling separately is: ```json { "error": "Pose not found", "reason": "no_map_in_range" } ``` That means no geo-fence was within range of the coordinate you supplied, which is a different problem from a map being found and the image failing to match. The first is a coverage or geo-referencing issue, the second is an imagery issue. Treat them differently in your client. ## Accuracy values The response carries position and orientation accuracy. These are nominal values rather than a per-query estimate, so do not read them as a confidence score for an individual pose. Use the `confidence` field on [Map Query](/fundamentals/rest-api-docs/map-query.md) when you need that. ## Related * [Map Query](/fundamentals/rest-api-docs/map-query.md), the native equivalent. * [GeoPose Support](/fundamentals/localization/geopose-support.md), the GeoPose object inside a normal response. * [Geo-fence](/fundamentals/georeferencing-maps/geo-fence.md), which coordinate-scoped requests depend on. --- # 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://docs.multiset.ai/fundamentals/rest-api-docs/oscp-geopose.md?ask=&goal= ``` `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.