---
title: "Use the reviewed maps contract"
description: "Separate order reads, marker grouping, device location, position writes, map providers, callouts, validation, and external handoffs."
canonical: https://docs.ordering.co/docs/developers/driver-app/maps-contract/
---

# Use the reviewed maps contract

Driver maps combine order reads, returned participant coordinates, device location, local grouping, map/image providers, optional Driver-position writes, validation, callout navigation, and external-app handoffs. No one stage proves another.

Marker visibility, distance text, provider render, callout navigation, or an open external app is not location, route, sharing, or completion proof.

## Availability

The signed-in **Map view** is gated by local permission state and a usable initial position. Order details can also open an internal destination map and direct address/provider handoffs.

Opening/focusing maps can start authenticated order reads, GPS/current-position work, location watching, map/image provider loads, and Driver-position request intent. A simulator is not a safe map runtime by default.

## Prerequisites

- Authenticated Driver scope and an authorized order context.
- Typed finite coordinates with explicit source, timestamp, trust/mock policy, and purpose.
- Separate permission-request/effective-grant evidence per platform/version.
- Provider adapters denied or replaced for evidence.
- No real address, coordinate, person, order, provider, or route in public fixtures.

## Responsibility boundaries

| Owner                    | Responsibility                                                      |
| ------------------------ | ------------------------------------------------------------------- |
| Order read API           | Return Driver-scoped orders and required participant fields         |
| Map controller           | Request data, group locally, hold loading/error/pagination state    |
| Marker UI                | Validate display inputs and present Driver/business/customer groups |
| Location provider        | Return device position/watch candidates with platform lifecycle     |
| Position API             | Authorize Driver self-scope and process location write/effects      |
| Map/image provider       | Render tiles/assets; never define order/location authorization      |
| Callout navigation       | Route locally to one detail or list without implying status         |
| External handoff         | Transfer destination to OS/provider with explicit user choice       |
| Product/security/privacy | Define freshness, mock, retention, sharing, provider policy         |

## Inputs and result

### Order read and grouping

Map view requests a fixed source-selected active-status order set, then groups returned orders locally by business and customer identifiers. One marker can represent several orders. Missing/malformed IDs or coordinates can change grouping and route behavior.

Results are loading, blank/unresolved map, Driver-only marker, participant markers, grouped callouts, error, or refresh. None is a complete/current order snapshot.

### Device location and writes

The App can request current position/watch. A nonzero candidate can trigger a Driver-position write. Current-source processing can update stored location/ timestamp and conditionally emit sockets, proximity work, and order trails.

Freshness/mock trust and affected status-location success are blocked pending server fixes and negative tests.

### Providers and handoffs

Internal maps use a provider and can load remote images. **Show in other maps** can enumerate provider candidates; direct address links use platform schemes. Declarations/queryability, installation, support, selection, open, route, guidance, arrival, and completion are distinct states.

## Security and privacy

- Authorize order and Driver scope before returning coordinates/PII.
- Validate finite ranges, source, freshness, mock policy, timestamp, and intended target before using coordinates for status or sharing.
- Never trust a client marker, permission gate, provider response, or external route as security validation.
- Minimize address/location retention and audience; keep exact provider schemes, identifiers and security findings private.
- Deny GPS, maps, images, address links, installed-app enumeration, sockets, and position writes in documentation fixtures.

## Limits and failure states

| State                           | Required interpretation                               |
| ------------------------------- | ----------------------------------------------------- |
| Blank map                       | Position/order/provider unresolved                    |
| Marker at zero/unexpected point | Invalid/stale input possible                          |
| Grouped callout                 | Local shared-key grouping, not group authorization    |
| Driver marker                   | Candidate position, not fresh/trusted/server-accepted |
| Position write response         | Not socket/trail/customer-visibility completion       |
| Provider item                   | Candidate, not installed/supported                    |
| Address link                    | Prepared handoff, not valid route                     |
| External app open               | Provider ownership, not navigation success            |

No complete state machine, atomic read/write/provider operation, safe retry, route accuracy, tracking, sharing, retention, or deployed success is established.

## Troubleshooting

### Markers are missing or grouped incorrectly

Validate typed IDs and finite coordinates in the source record. Do not infer no order or merge/split records from the UI alone.

### Driver location looks stale

Treat device candidate, stored location, timestamp, provider render, API write, socket and customer visibility separately. Do not refresh repeatedly.

### A provider is listed but does not open

Candidate listing does not prove installation/support. Cancel and use the operator-approved handoff after destination validation.

### A direct address opens the wrong place

Stop guidance. Validate address and coordinates through the authoritative order owner; do not edit or try alternate schemes from Driver App.

### A map test passes

Confirm the provider/GPS/network/write adapters were inert and the fixture used finite fake data. Otherwise treat it as source support only.

**Related guides:** [Use the delivery map](https://docs.ordering.co/docs/products/driver-app/maps/delivery-map/) · [Open external navigation](https://docs.ordering.co/docs/products/driver-app/maps/open-navigation/) · [Understand location permissions](https://docs.ordering.co/docs/products/driver-app/maps/location-permissions/)