[jeffersontuc]

Summary

SDD Lite spec for migrating GeolocationInput from the legacy Places API (places.Autocomplete / places.SearchBox, which call AutocompletionService.GetPredictions / GetQueryPredictions) to Places API (New) (AutocompleteSuggestion, AutocompleteSessionToken, Place.fetchFields).

Google Cloud projects created after 2025-03-01 cannot enable the legacy Places API, so their keys get LegacyApiNotActivatedMapError and address search returns no suggestions.

What the spec defines

• No breaking changes. All changes stay inside react/geolocation/. index.ts, components.ts, inputs.ts, types/rules.ts, react/country/*.ts and the exported component props are untouched. Ships as a minor release.
• Adapter from the new Place to the legacy PlaceResult shape, so geolocationAutoCompleteAddress and all country geolocation rules and handlers keep working as they are.
• Own suggestions dropdown under the existing Input, instead of PlaceAutocompleteElement. It keeps the .pac-container / .pac-item classes for omnishipping Cypress tests and merchant CSS, and follows the WAI-ARIA combobox pattern.
• New API first, legacy fallback when the new API is not enabled or not available. The fallback holds for the whole page and logs one Splunk event (logPlacesApiFallback).
• useSearchBox keeps its current behavior; place details request only Essentials fields; no new i18n keys; no new dependencies.

Consumers

vtex.omnishipping, vtex.shipping-preview and vtex.checkout need no code changes. They will be QA'd on a linked workspace before release.

Next step

Review the spec, set Status: Approved, merge, then run /implementing specs/places-api-new-migration.md.

🤖 Generated with Claude Code

[vtex-io-ci-cd]

Hi! I'm VTEX IO CI/CD Bot and I'll be helping you to publish your app! 🤖

Please select which version do you want to release:

• Patch (backwards-compatible bug fixes)

• Minor (backwards-compatible functionality)

• Major (incompatible API changes)

And then you just need to merge your PR when you are ready! There is no need to create a release commit/tag.

• No thanks, I would rather do it manually 😞

[sonar-workflows]

Quality Gate passed

Issues

• 0 New Issues
• 0 Fixed Issues
• 0 Accepted Issues

Measures

• 0 Security Hotspots
• No data about coverage (75.00% Estimated after merge)
• No data about duplications (20.40% Estimated after merge)

Project ID: address-form

View in SonarQube

[dk-pr-review]

[Functional.Support] 🟡 RESTRICT

The spec is introduced already marked Status: Approved, which skips the SDD Lite flow in AGENTS.md: spec PRs should open with Status: Draft, be reviewed, and only then be manually flipped to Approved before merge. As submitted there is no evidence the Draft review step happened for this document.

Action: If this PR is the initial spec submission, set Status: Draft and let the reviewer flip it to Approved after sign-off, per the documented SDD Lite workflow.

To contest this finding, reply in this thread

[dk-pr-review]

DK Review — Audit Summary

Verdict: ⚠️ RESTRICTED

Severity	Count
BLOCK	0
RESTRICT	1
SUGGEST	2

Only BLOCK and RESTRICT findings anchored to a changed line are commented inline on the diff. The other 2 findings below open no review thread.

Scenarios evaluated: general-review
Scenarios skipped: dependency-governance (no matching files), pipeline-config (no matching files), feature-flags (no matching files), agent-skills-review (no matching files), quality-ratchet (no matching files)

---

📋 Findings (3)

RESTRICT

1. [Functional.Support] specs/places-api-new-migration.md:3 — The spec is introduced already marked Status: Approved, which skips the SDD Lite flow in AGENTS.md: spec PRs should open with Status: Draft, be reviewed, and only then be manually flipped to Approved before merge. As submitted there is no evidence the Draft review step happened for this document.
   → If this PR is the initial spec submission, set Status: Draft and let the reviewer flip it to Approved after sign-off, per the documented SDD Lite workflow.

SUGGEST

1. [Functional.Support] specs/places-api-new-migration.md:1 — AGENTS.md's SDD Lite/Full decision table favors Full for 'significant architectural impact' and 'high ambiguity'. This spec introduces a new provider abstraction, 4 user stories, 12 scenarios, multiple ADRs with rejected alternatives, and requires QA coordination in a separate omnishipping workspace — closer to the Full criteria than the '<5 days / low ambiguity / no cross-consumer coordination' Lite criteria, even though no public export changes are involved.
   → Consider whether this effort should go through SDD Full (Spec Kit) given its scope and the omnishipping QA dependency, or explicitly justify why Lite is sufficient despite the complexity.
2. [general.documentation-gap] specs/places-api-new-migration.md:97 — The Cost NFR only accounts for 'one autocomplete session plus one Place Details (Essentials fields) per completed selection,' but US-4/FR-10 also introduces a Place.searchByText call in useSearchBox fallback mode (when Enter is pressed with no suggestions loaded). Text Search billing is separate from session-token-based Autocomplete+Details billing and isn't captured in the cost estimate.
   → Add the searchByText cost (and its session-token applicability, if any) to the Cost NFR so the team owning Maps billing gets an accurate estimate.

---

DK Review v1.0.0 | To contest a finding, reply in its thread

[jeffersontuc]

Closing in favor of #711, which now carries this spec (specs/places-api-new-migration.md) together with its implementation. The DK review findings from this PR were carried over to #711's description.