AdminConsole
Tutorials/Intermediate
Intermediate35 minWeb + REST

Build a route preview with alternatives

Resolve endpoints, request alternatives, decode geometry, and explain toll/time trade-offs.

By the endA production-pattern route comparison view.
Real-world scenario

Build against an explicit contract

A travel-planning page must compare route alternatives without presenting distance, toll, and ETA as timeless facts.

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 travel-planning page must compare route alternatives without presenting distance, toll, and ETA as timeless facts. Record the region, data freshness, latency budget, privacy purpose, credential owner, and fallback before choosing an SDK or endpoint.

Step 2

Resolve route endpoints once

Convert user intent to stable Mappls Pins or validated coordinates before routing. Never geocode the same free-form text independently for each alternative.

Routes & Navigation · SDK or product slice
val route = MapplsDirections.builder()
  .origin("MMI000")
  .destination("MMI001")
  .profile(DirectionsCriteria.PROFILE_DRIVING)
  .resource(DirectionsCriteria.RESOURCE_ROUTE)
  .steps(true)
  .build()

route.enqueueCall(object : Callback<DirectionsResponse> {
  override fun onResponse(call: Call<DirectionsResponse>, response: Response<DirectionsResponse>) {
    val primaryRoute = response.body()?.routes()?.firstOrNull()
  }
  override fun onFailure(call: Call<DirectionsResponse>, error: Throwable) = Unit
})
Step 3

Request and normalize alternatives

Choose an explicit profile, units, exclusions, and alternatives policy; retain provider route identity and request time with every decoded geometry.

Step 4

Explain the choice

Draw alternatives with non-color cues, summarize distance/time/toll trade-offs, and mark the preview stale when endpoints, profile, traffic horizon, or itinerary change.

Step 5

Prove the production behavior

Automate the happy path and every named failure. The release is ready only when all alternatives share identical endpoints and profile; unreachable routes produce an honest state; a stale preview cannot start navigation. Capture provider request identity without logging credentials or unnecessary precise location.

Recovery design

Failure modes you must exercise

one endpoint is unresolved

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

provider returns no route

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

late response targets an obsolete itinerary

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

all alternatives share identical endpoints and profileunreachable routes produce an honest statea stale preview cannot start navigation

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 Coordinated incident response 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.