{"generatedAt":"2026-10-03T18:51:39.441Z","product":{"slug":"search-places","name":"Search & Places","summary":"Autosuggest, geocoding, nearby discovery, place details, and Mappls Pin addressing.","stateModel":"stateless","platforms":["REST","Web","Android","iOS","React Native","Flutter","Widgets"],"auth":{"type":"Restricted static key (current) or OAuth bearer (legacy)","guidance":"Current core REST uses a restricted static key in the documented access_token query contract. The pre-August-2025 line uses OAuth bearer with legacy hosts and paths. Never mix generations; keep server-use keys off untrusted clients and request logs."}},"ownership":{"classification":"application-stateful","boundary":"Search & Places is stateless at the product boundary for this catalog, while the published consent, selection, inspection, or publication journeys are application-owned state machines. Do not attribute those states to Mappls.","applicationRule":"The application owns business identity, expected version, command idempotency, evidence receipts, audit, reconciliation, and downstream side effects even when Mappls owns provider resource state."},"coverage":{"slug":"search-places","name":"Search & Places","stateModel":"stateless","ownership":"application-stateful","accent":"#00a88f","journeyCount":1,"boundary":"Search & Places is stateless at the product boundary for this catalog, while the published consent, selection, inspection, or publication journeys are application-owned state machines. Do not attribute those states to Mappls.","aggregates":["address verification"],"journeySlugs":["consented-address-verification"],"sampleSlugs":["address-verifier"],"tutorialSlugs":["address-autocomplete","nearby-discovery","mappls-mcp-agent","a2a-solution-coordination","oauth-server-integration","flutter-map","rest-geocode-service","reverse-geocode-check-in","web-widget-place-picker","cordova-map","xamarin-map","distance-matrix-dispatch","cordova-release-hardening","deep-link-attribution-resilience","flutter-production-lifecycle","ios-sdk-production-readiness","react-native-native-parity","widget-host-production","xamarin-maintenance-migration"],"useCaseSlugs":["last-mile-delivery","ride-hailing","retail-expansion","banking-address-risk","hospital-care-logistics","emergency-response","connected-vehicle","travel-discovery"],"contractSlugs":["core-location-get-api-places-search-json-autosuggest-api","core-location-get-rest-key-rev-geocode-reverse-geocode-api"],"sourceGuideSlugs":["mappls-rest-apis"],"totals":{"states":9,"transitions":11,"failurePlans":4,"durableRecords":5,"operationalSignals":8}},"controlLayers":[{"id":"identity","title":"Identity and aggregate boundary","question":"What durable thing is being operated?","implementation":"Use stable business and provider identifiers for address verification; never infer identity from display text or the latest coordinates.","proof":"Duplicate creation, resource rebinding, tenant isolation, and retirement tests."},{"id":"authority","title":"Actor authority","question":"Who may advance each transition?","implementation":"Authorize every command against the named journey actors: Application user, Evidence capture application, Policy service, Human reviewer, Privacy service. Persist the attributable actor, tenant, purpose, and policy decision.","proof":"Role, resource, tenant, purpose, and human-approval denial tests."},{"id":"commands","title":"Commands and concurrency","question":"How are retries and races made safe?","implementation":"Require a command idempotency key and expected aggregate version. Cache the canonical result, reject key reuse with different intent, and reconcile ambiguous timeouts before retry.","proof":"Exact replay, stale-version rejection, concurrent-writer, timeout, and restart tests."},{"id":"evidence","title":"Evidence and durable records","question":"What proves each state?","implementation":"Persist immutable receipts and revisions around these catalog records: Verification aggregate, Normalized address, Consent grant, Evidence envelope, Decision record. Keep event time, receipt time, source identity, hashes, and retention policy separate.","proof":"Missing, malformed, late, duplicate, conflicting, and redacted-evidence tests."},{"id":"events","title":"Events and side effects","question":"How do downstream systems learn what committed?","implementation":"Commit aggregate state, audit, and a transactional outbox together. Sign deliveries, bound retries, dead-letter exhaustions, and preserve delivery attempts without changing business history.","proof":"Atomic commit, signature, retry, lease fencing, dead-letter, replay, and ordering tests."},{"id":"recovery","title":"Recovery and reconciliation","question":"What happens when systems disagree?","implementation":"Treat timeouts as unknown outcomes, poll or consume authoritative evidence, compare versions, append a reconciliation decision, and use compensation instead of destructive history edits.","proof":"Provider timeout, callback-before-response, delayed event, outage, restart, and manual-recovery drills."},{"id":"privacy","title":"Privacy and human control","question":"Which data and decisions are sensitive?","implementation":"Minimize precise location and media, scope retention, redact derived data deliberately, and require attributable approval for dispatch, publication, access, closure, and destructive change where consequential.","proof":"Least-privilege, consent expiry, separation-of-duties, retention, export, revocation, and redaction tests."},{"id":"operations","title":"Operations and release","question":"Can operators see and recover the journey?","implementation":"Expose state age, source freshness, stuck commands, retries, reconciliation lag, outbox depth, terminal outcomes, and per-aggregate audit. Roll out behind explicit acceptance gates.","proof":"SLO alerts, support lookup, bulk reconciliation, rollback, backup restore, regional failover, and incident drills."}],"journeys":[{"slug":"consented-address-verification","title":"Consented address verification","eyebrow":"Search & Places · purpose-bound evidence decision","productSlug":"search-places","stateModel":"stateful","summary":"Normalize a declared service address, capture purpose-bound device evidence, apply an explainable versioned policy, require human review where evidence is weak, and retire precise data without erasing accountability.","aggregate":"address verification","actors":["Application user","Evidence capture application","Policy service","Human reviewer","Privacy service"],"sourceGuideSlugs":["mappls-rest-apis"],"contractSlugs":["core-location-get-api-places-search-json-autosuggest-api","core-location-get-rest-key-rev-geocode-reverse-geocode-api"],"sampleSlug":"address-verifier","states":[{"id":"entered","label":"Entered","meaning":"One external business reference, opaque subject reference, declared purpose, and raw address intent are recorded.","recovery":"Reconcile by external reference and idempotency key instead of minting a duplicate verification."},{"id":"normalized","label":"Normalized","meaning":"The declared address maps to a provider-backed Mappls Pin, coordinate, components, confidence, and provenance.","recovery":"Keep ambiguous candidates visible and request subject or operator confirmation before capture."},{"id":"capture_authorized","label":"Capture authorized","meaning":"A specific subject granted one purpose-bound, expiring, accuracy- and retention-governed evidence capture.","recovery":"Reject expired or withdrawn grants and issue a new consent event when purpose or policy changes."},{"id":"evidence_captured","label":"Evidence captured","meaning":"Immutable source identity, event and receipt time, coordinate, accuracy, provider context, and integrity hash are committed.","recovery":"Deduplicate by source event and preserve conflicting or late observations as separate evidence rather than overwriting them."},{"id":"compared","label":"Compared","meaning":"A versioned policy records distance, effective uncertainty, thresholds, and its verify, reject, or review recommendation.","recovery":"Recompute only as a new policy decision version and retain the earlier recommendation."},{"id":"review_required","label":"Review required","meaning":"Weak, conflicting, or policy-sensitive evidence is assigned to an attributable human decision.","recovery":"Keep the case pending with an SLA; never auto-verify merely because a review queue is unavailable."},{"id":"verified","label":"Verified","meaning":"A policy or human decision accepted the declared address for the exact recorded purpose.","recovery":"A later change creates a linked verification; it does not rewrite the evidence and policy that supported this outcome.","terminal":true},{"id":"rejected","label":"Rejected","meaning":"Evidence did not establish the declared address, with reason, recommendation, actor, and appeal path retained.","recovery":"Offer correction or a new independent attempt without exposing sensitive fraud or policy signals.","terminal":true},{"id":"cancelled","label":"Cancelled","meaning":"Consent was withdrawn before evidence capture and no precise observation may be accepted.","recovery":"A later attempt requires a fresh purpose-bound consent, not reactivation of the revoked grant.","terminal":true}],"transitions":[{"command":"enter_verification","actor":"Application user","from":[],"to":"entered","event":"address_verification.entered","idempotency":"Use the external application or case reference as durable business identity."},{"command":"normalize_address","actor":"Policy service","from":["entered"],"to":"normalized","event":"address_verification.normalized","idempotency":"Bind normalized provider response to address-input hash and request identity."},{"command":"authorize_capture","actor":"Application user","from":["normalized"],"to":"capture_authorized","event":"address_verification.capture_authorized","idempotency":"Consent identity, text version, subject, purpose, expiry, and retention policy form one grant."},{"command":"revoke_consent","actor":"Application user","from":["capture_authorized"],"to":"cancelled","event":"address_verification.consent_revoked","idempotency":"Commit withdrawal once and reject all later evidence under that grant."},{"command":"capture_evidence","actor":"Evidence capture application","from":["capture_authorized"],"to":"evidence_captured","event":"address_verification.evidence_captured","idempotency":"Use a device-generated source-event identity created before transmission."},{"command":"compare","actor":"Policy service","from":["evidence_captured"],"to":"compared","event":"address_verification.compared","idempotency":"Evidence hash, normalized-place version, and policy version identify the exact comparison."},{"command":"verify","actor":"Policy service","from":["compared"],"to":"verified","event":"address_verification.verified","idempotency":"Bind the terminal decision to comparison and aggregate version."},{"command":"reject","actor":"Policy service","from":["compared"],"to":"rejected","event":"address_verification.rejected","idempotency":"Bind the terminal decision to comparison and aggregate version."},{"command":"defer","actor":"Policy service","from":["compared"],"to":"review_required","event":"address_verification.review_required","idempotency":"Create one review case per comparison version."},{"command":"review_verify","actor":"Human reviewer","from":["review_required"],"to":"verified","event":"address_verification.verified","idempotency":"Reviewer decision records reason, independent evidence, and any override under one identity."},{"command":"review_reject","actor":"Human reviewer","from":["review_required"],"to":"rejected","event":"address_verification.rejected","idempotency":"Reviewer decision records reason, independent evidence, and any override under one identity."}],"invariants":["One external business reference maps to one verification aggregate.","Precise evidence is accepted only under active consent for the exact declared purpose and time window.","Provider normalization and application policy are identified separately.","An automated actor cannot override its own policy recommendation.","Every terminal outcome retains evidence hash, policy version, actor, and attributable reason.","Precise evidence can be redacted without erasing the audit trail or claiming that retained hashes can reconstruct it."],"records":[{"name":"Verification aggregate","purpose":"Business identity, purpose, lifecycle, selected evidence, comparison, decision, and version.","keyFields":["verificationId","externalReference","subjectReference","purpose","state","version"]},{"name":"Normalized address","purpose":"Provider-backed place identity and address interpretation.","keyFields":["mapplsPin","coordinate","formattedAddress","components","confidence","provenance"]},{"name":"Consent grant","purpose":"Attributable authority and privacy bounds for precise capture.","keyFields":["consentId","subject","purpose","textVersion","grantedAt","expiresAt","retentionUntil","status"]},{"name":"Evidence envelope","purpose":"Immutable device observation with quality, timing, provenance, and integrity identity.","keyFields":["evidenceId","sourceEventId","eventTime","receivedAt","coordinate","accuracy","contentHash"]},{"name":"Decision record","purpose":"Explainable recommendation, human disposition, override, and appeal context.","keyFields":["policyVersion","thresholds","recommendation","outcome","actor","reason"]}],"failures":[{"trigger":"Capture arrives after consent expiry or withdrawal","detection":"Receipt or evidence event falls outside the committed grant window or grant status is revoked.","recovery":"Reject it without retaining precise payload and require a fresh consent for another attempt."},{"trigger":"Device evidence is replayed","detection":"Source-event identity or content hash already belongs to an accepted evidence envelope.","recovery":"Return the original result for an idempotent retry or reject conflicting reuse as a security event."},{"trigger":"Address candidate is ambiguous or evidence accuracy is weak","detection":"Provider confidence, device accuracy, separation, or policy combination enters the review band.","recovery":"Request clarification or independent review; do not transform uncertainty into a definitive match."},{"trigger":"Retention deadline passes","detection":"Precise evidence remains present beyond purpose, tenant, or jurisdiction policy.","recovery":"Redact coordinate and place payloads, retain the minimum decision and integrity record, and audit completion."}],"observability":["Normalization confidence, ambiguity, latency, and provider failures","Consent grant, expiry, withdrawal, and out-of-window capture attempts","Evidence accuracy, age, source integrity, replay, and mock-location risk","Distance and recommendation distribution by versioned policy","Review queue age, outcome, override rate, and supporting-evidence class","False-match, false-reject, correction, and appeal outcomes","Precise-data access, export, retention expiry, redaction, and legal hold","Idempotency conflicts, version conflicts, outbox backlog, and restart recovery"],"website":"/journeys/consented-address-verification"}],"evidence":{"contracts":[{"slug":"core-location-get-api-places-search-json-autosuggest-api","method":"GET","path":"/api/places/search/json","summary":"AutoSuggest API","contractStatus":"legacy-source","stateModel":"stateless","journeyRole":"request-response","website":"/api-reference/core-location-get-api-places-search-json-autosuggest-api"},{"slug":"core-location-get-rest-key-rev-geocode-reverse-geocode-api","method":"GET","path":"/{REST_KEY}/rev_geocode","summary":"Reverse Geocode API","contractStatus":"legacy-source","stateModel":"stateless","journeyRole":"request-response","website":"/api-reference/core-location-get-rest-key-rev-geocode-reverse-geocode-api"}],"guides":[{"slug":"mappls-rest-apis","title":"Mappls Map APIs (REST) !","summary":"Building Blocks to Add Powerful Location Intelligence & Mapping Functionality to your Apps","kind":"REST API","maturity":"current","platforms":["REST"],"website":"/reference/mappls-rest-apis"}],"samples":[{"slug":"address-verifier","name":"Address Verifier","description":"Normalize an address, govern consented device evidence, apply versioned policy, and retain an attributable decision.","stack":["Node.js","Browser trust studio","Search adapter","Evidence ledger"],"implementation":"full-stack-reference","verifiedTestCount":8,"downloadPath":"/downloads/address-verifier.zip","website":"/samples/address-verifier"}],"tutorials":[{"slug":"address-autocomplete","title":"Build address autocomplete that users trust","outcome":"An accessible, resilient delivery-address field.","level":"Beginner","duration":"20 min","website":"/tutorials/address-autocomplete"},{"slug":"nearby-discovery","title":"Create a nearby discovery experience","outcome":"A map-and-list place explorer.","level":"Intermediate","duration":"40 min","website":"/tutorials/nearby-discovery"},{"slug":"mappls-mcp-agent","title":"Give an AI agent grounded Mappls tools","outcome":"An agent that can reason about real places without inventing APIs.","level":"Intermediate","duration":"30 min","website":"/tutorials/mappls-mcp-agent"},{"slug":"a2a-solution-coordination","title":"Coordinate a complete Mappls A2A journey","outcome":"A restart-safe OAuth-capable host that keeps transport identity, provider-read purpose, protocol completion, human acceptance, entitlement, writes, and production approval separate.","level":"Advanced","duration":"90 min","website":"/tutorials/a2a-solution-coordination"},{"slug":"oauth-server-integration","title":"Call Mappls safely from a trusted server","outcome":"A credential-safe live server boundary with typed errors, timeout, retry, and provider provenance.","level":"Intermediate","duration":"35 min","website":"/tutorials/oauth-server-integration"},{"slug":"flutter-map","title":"Build a Flutter map and place picker","outcome":"A reusable cross-platform location field.","level":"Intermediate","duration":"45 min","website":"/tutorials/flutter-map"},{"slug":"rest-geocode-service","title":"Build a server-side geocoding boundary","outcome":"A credential-safe geocoding service with typed errors and provenance.","level":"Beginner","duration":"25 min","website":"/tutorials/rest-geocode-service"},{"slug":"reverse-geocode-check-in","title":"Turn a device fix into a trustworthy check-in","outcome":"A privacy-aware check-in that retains both raw evidence and human-readable context.","level":"Beginner","duration":"30 min","website":"/tutorials/reverse-geocode-check-in"},{"slug":"web-widget-place-picker","title":"Embed a place picker widget","outcome":"An accessible embedded place picker with explicit host-page ownership.","level":"Beginner","duration":"25 min","website":"/tutorials/web-widget-place-picker"},{"slug":"cordova-map","title":"Ship a Mappls map in Cordova and Ionic","outcome":"A hybrid map screen with lifecycle-safe native bridge handling.","level":"Intermediate","duration":"50 min","website":"/tutorials/cordova-map"},{"slug":"xamarin-map","title":"Integrate Mappls into a Xamarin application","outcome":"A shared-code location feature backed by correctly owned native map views.","level":"Intermediate","duration":"55 min","website":"/tutorials/xamarin-map"},{"slug":"distance-matrix-dispatch","title":"Rank responders with a distance matrix","outcome":"An explainable ETA-based dispatch shortlist rather than a straight-line guess.","level":"Intermediate","duration":"45 min","website":"/tutorials/distance-matrix-dispatch"},{"slug":"cordova-release-hardening","title":"Qualify a Cordova location release","outcome":"A versioned hybrid release with reproducible native builds, safe teardown, and rollback.","level":"Advanced","duration":"80 min","website":"/tutorials/cordova-release-hardening"},{"slug":"deep-link-attribution-resilience","title":"Operate deep links across every hand-off","outcome":"A measurable zero-SDK journey that never confuses a click with arrival.","level":"Advanced","duration":"70 min","website":"/tutorials/deep-link-attribution-resilience"},{"slug":"flutter-production-lifecycle","title":"Production-harden a Flutter location feature","outcome":"A cross-platform feature with stable identity, bounded bridge traffic, and deterministic disposal.","level":"Advanced","duration":"90 min","website":"/tutorials/flutter-production-lifecycle"},{"slug":"ios-sdk-production-readiness","title":"Qualify an iOS Mappls release","outcome":"A clean-device iOS qualification record spanning SDK, widget, tracking, and distribution boundaries.","level":"Advanced","duration":"2 hr","website":"/tutorials/ios-sdk-production-readiness"},{"slug":"react-native-native-parity","title":"Qualify React Native native parity","outcome":"One JavaScript contract backed by independently qualified Android and iOS behavior.","level":"Advanced","duration":"100 min","website":"/tutorials/react-native-native-parity"},{"slug":"widget-host-production","title":"Operate widgets as untrusted lifecycle surfaces","outcome":"A restart-safe host journey with exact-origin validation and a complete non-widget fallback.","level":"Advanced","duration":"85 min","website":"/tutorials/widget-host-production"},{"slug":"xamarin-maintenance-migration","title":"Harden and migrate a Xamarin location feature","outcome":"A supportable existing integration with explicit compatibility, teardown, and migration evidence.","level":"Advanced","duration":"2 hr","website":"/tutorials/xamarin-maintenance-migration"}],"useCases":[{"slug":"last-mile-delivery","title":"A delivery promise customers can trust","industry":"Logistics","outcome":"Fewer failed deliveries and a live, explainable ETA from checkout to doorstep.","website":"/use-cases/last-mile-delivery"},{"slug":"ride-hailing","title":"A pickup flow that survives the real world","industry":"Mobility","outcome":"Shorter pickup times with fewer calls, cancellations, and unsafe rendezvous points.","website":"/use-cases/ride-hailing"},{"slug":"retail-expansion","title":"Choose the next store with evidence","industry":"Retail","outcome":"Faster site screening and investment decisions grounded in a reusable spatial model.","website":"/use-cases/retail-expansion"},{"slug":"banking-address-risk","title":"Make address risk explainable","industry":"Financial services","outcome":"More straight-through approvals with a clear audit trail for ambiguous or high-risk addresses.","website":"/use-cases/banking-address-risk"},{"slug":"hospital-care-logistics","title":"Coordinate time-critical care without losing custody","industry":"Healthcare","outcome":"Shorter transfer and specimen journeys with fewer missed hand-offs and a complete chain of operational custody.","website":"/use-cases/hospital-care-logistics"},{"slug":"emergency-response","title":"Route coordinated response under pressure","industry":"Public safety","outcome":"Reduced time to scene and safer decisions across dispatch, responders, and command.","website":"/use-cases/emergency-response"},{"slug":"connected-vehicle","title":"Navigation built for intermittent connectivity","industry":"Automotive","outcome":"Reliable guidance across coverage gaps without giving up traffic, search freshness, or safety.","website":"/use-cases/connected-vehicle"},{"slug":"travel-discovery","title":"Turn inspiration into an itinerary","industry":"Travel","outcome":"More confident trip planning and higher conversion from discovery to booking.","website":"/use-cases/travel-discovery"}]},"releaseGates":["Every command has tenant, actor, purpose, idempotency, expected-version, and authorization evidence.","Every state transition has an objective evidence rule and an explicit recovery path.","Provider and business identities remain distinct, versioned, and reconcilable.","Timeout, retry, duplicate, late, out-of-order, conflict, restart, and outage paths are tested.","Sensitive location, media, identity, and operational evidence has consent, access, retention, and redaction policy.","Audit and outbox commit atomically; signing, delivery, dead-letter, replay, and lease fencing are verified.","Operators can find one aggregate, explain its state, repair safely, and prove who acted.","Live Mappls entitlement, quota, regional behavior, callbacks, and exact provider contracts are validated before production."],"handoffs":{"website":"https://developer.mappls.com/tools/stateful?product=search-places","api":"https://developer.mappls.com/api/stateful-plan?product=search-places","console":"https://developer.mappls.com/console/apps","resource":"mappls://catalog/stateful","tool":"mappls_plan_stateful_integration"},"credentialRule":"The planner accepts no credential, token, secret, precise location, media, or provider resource identifier."}