AdminConsole
Tutorials/Beginner
Beginner30 minREST

Turn a device fix into a trustworthy check-in

Reverse geocode accuracy-bearing coordinates, preserve consent, and distinguish evidence from an address label.

By the endA privacy-aware check-in that retains both raw evidence and human-readable context.
Real-world scenario

Build against an explicit contract

A field check-in must attach readable place context to a consented device fix without pretending reverse geocoding proves physical presence.

A Mappls developer projectA restricted REST applicationFixture data with no production credentialsA request, aggregate, or correlation ID strategy
Step 1

Define the user and system contract

A field check-in must attach readable place context to a consented device fix without pretending reverse geocoding proves physical presence. Record the region, data freshness, latency budget, privacy purpose, credential owner, and fallback before choosing an SDK or endpoint.

Step 2

Capture purpose-bound evidence

Record consent version, purpose, event and receipt time, latitude/longitude, accuracy, source, and expiry separately from the eventual address label.

Search & Places · SDK or product slice
import { createMapplsClientFromEnvironment } from "@mappls/server-sdk";

// MAPPLS_STATIC_KEY is applied using the current documented query contract.
// Keep the restricted key inside this trusted server process.
const mappls = createMapplsClientFromEnvironment();
const suggestions = await mappls.autosuggest({
  query: "coffee",
  region: "IND"
});
Step 3

Reverse geocode on the server

Validate coordinate and accuracy bounds, call with a trusted credential, retain provider identity, and store the raw evidence hash plus normalized response fields.

Step 4

Apply a versioned decision policy

Compare fix accuracy, age, distance to target, and geofence policy; send weak evidence to review and permit consent revocation or precise-data redaction.

Step 5

Prove the production behavior

Automate the happy path and every named failure. The release is ready only when address text never replaces raw accuracy evidence; weak fixes cannot auto-approve; redaction preserves decision lineage. Capture provider request identity without logging credentials or unnecessary precise location.

Recovery design

Failure modes you must exercise

permission or consent absent

Fail fast with a typed, user-safe outcome and preserve the original request identity.

stale or inaccurate fix

Keep the last verified state, mark freshness honestly, and retry only within the documented idempotency boundary.

reverse geocoder returns no address

Reconcile durable local and provider evidence before declaring success or issuing a compensating command.

Never turn uncertainty into success

Timeout after a stateful command is an unknown outcome. Query by provider/idempotency identity or wait for authoritative events; do not blindly retry a new command.

Acceptance criteria

Definition of done

address text never replaces raw accuracy evidenceweak fixes cannot auto-approveredaction preserves decision lineage

REST production checks

Credentials never reach a browser or mobile bundleTimeout, retry, and idempotency policies are explicitCoordinates, addresses, and identifiers have data-retention rulesEvery operation is attributable in logs and usage reporting
Grounded implementation

Continue from source, contracts, and a full app

These links resolve to repository-derived evidence; unsupported package names and endpoints are not filled in from guesswork.

Study the complete Consented address verification state machine
Tutorial complete

Run it, break it, then observe it

Start with fixture credentials, execute the failure plan, and use request logs, usage, webhook evidence, and operational metrics before promoting traffic.