AdminConsole
Tutorials/Intermediate
Intermediate40 minWeb

Create a nearby discovery experience

Combine category search, viewport updates, result cards, and map selection.

By the endA map-and-list place explorer.
Real-world scenario

Build against an explicit contract

A health-services finder must keep map, result list, filters, and selected place synchronized while enforcing eligibility before distance ranking.

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

Define the user and system contract

A health-services finder must keep map, result list, filters, and selected place synchronized while enforcing eligibility before distance ranking. Record the region, data freshness, latency budget, privacy purpose, credential owner, and fallback before choosing an SDK or endpoint.

Step 2

Define the search area

Use an explicit center and radius or visible viewport, cap repeated map-move searches, and show when results describe an older viewport.

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

Apply eligibility before ranking

Intersect category, service, opening, accessibility, and business constraints before sorting by distance or ETA.

Step 4

Preserve one selected identity

Use the Mappls Pin as the shared key across marker, card, details, route preview, and deep-link hand-off; never join on display name.

Step 5

Prove the production behavior

Automate the happy path and every named failure. The release is ready only when map and list expose the same eligible set; empty states explain the active constraints; selection survives reordering and viewport refresh. Capture provider request identity without logging credentials or unnecessary precise location.

Recovery design

Failure modes you must exercise

location unavailable

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

provider results outside requested radius

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

selected place disappears after filter change

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

map and list expose the same eligible setempty states explain the active constraintsselection survives reordering and viewport refresh

Web production checks

Origin restrictions include every deployed hostnameMap lifecycle follows the framework lifecycleLarge datasets are tiled, clustered, or progressively loadedKeyboard, touch, reduced-motion, and failure states are tested
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.