feat: Introduce Location Search + Lookup capabilities

[jingyli]

Description

A mirror copy of #545 that supersedes it.

Defines standard interfaces for discovering, searching, and retrieving physical locations (e.g., retail stores, restaurants, warehouses, lodging properties).

It introduces two new capabilities under the dev.ucp.common namespace (consistent with Shopping's Catalog capability design):

1. Location Search (dev.ucp.common.location.search): Discovery-focused endpoint for natural language query, geographic, and offerings-based filters.
2. Location Lookup (dev.ucp.common.location.lookup): Resolution-focused endpoints supporting single & batch lookups.

Some key commerce flows it will be able to unlock:

• Local Pickup Discovery: Finding locations like retail stores or restaurant branches
  nearby that support customer pickup and checking their operating hours & inventory availability
  before selection.
• Fulfillment Area Verification: Checking if a specific location (e.g., utility depot, restaurant,
  or local service provider) has delivery coverage for a buyer's address.

Category (Required)

• Core Protocol: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical Council approval)
• Governance/Contributing: Updates to GOVERNANCE.md, CONTRIBUTING.md, or CODEOWNERS. (Requires Governance Council approval)
• Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
• Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
• Infrastructure: CI/CD, Linters, or build scripts. (Requires DevOps Maintainer approval)
• Maintenance: Version bumps, lockfile updates, or minor bug fixes. (Requires DevOps Maintainer approval)
• SDK: Language-specific SDK updates and releases. (Requires DevOps Maintainer approval)
• Samples / Conformance: Maintaining samples and the conformance suite. (Requires Maintainer approval)
• UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator). (Requires Maintainer approval)
• Community Health (.github): Updates to templates, workflows, or org-level configs. (Requires DevOps Maintainer approval)

Related Issues

This is related to RFC #375's section 10.

Checklist

• I have followed the Contributing Guide (including Conventional Commits title requirements and ! for breaking changes).
• I have updated the documentation (if applicable).
• My changes pass all local linting and formatting checks.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• (For Core/Capability) I have included/updated the relevant JSON schemas.
• I have regenerated Python Pydantic models by running generate_models.sh under python_sdk.

Screenshots / Logs (if applicable)

[igrigorik]

Overall, the shape and proposal make sense—ty for scaffolding this. A few design questions I'd like to work through...

1. Should common be the service, or the namespace containing a Location service?

The capability names are scoped to Location:

dev.ucp.common.location.search
dev.ucp.common.location.lookup

The profile examples, however, advertise the transport as:

{
  "services": {
    "dev.ucp.common": [{ "...": "..." }]
  }
}

I agree with dev.ucp.common.* as the namespace for cross-vertical primitives. However, I'm not sure about making dev.ucp.common one catch-all service: every future shared capability would then share an endpoint, transport schema, etc.

The alternative split is:

namespace:    dev.ucp.common.*
service:      dev.ucp.common.location
capabilities: dev.ucp.common.location.search
              dev.ucp.common.location.lookup

Do we think a catch-all .common service is preferred to scoped services?

2. Is geofence_radius sufficient to model the domain?

The current geo object combines a physical point with a circular geofence_radius, while geofence_point asks whether a requested point falls inside that circle. This covers a useful simple case, but in my experience service areas are often irregular polygons, disjoint regions, postal-code unions, etc.

Do we need to model (thin, hopefully) RFC 7946-based service-area shape supporting Polygon / MultiPolygon?

3. Can we adopt a Schema.org-inspired shape instead of inventing a bespoke one?

The latest changes make the custom model deterministic by defining 24:00, precedence between is_closed / is_24_hours / intervals, and a two-entry convention for overnight hours. That is an improvement, but it also highlights how much new protocol syntax and interpretation logic we are defining.

Schema.org's OpeningHoursSpecification already provides the core semantics we need:

• dayOfWeek, opens, and closes;
• multiple entries for split shifts;
• closes < opens means the interval spans the next day;
• no opens means closed;
• validFrom / validThrough cover date-specific exceptions.

A Schema.org-inspired UCP shape could look like:

{
  "timezone": "America/New_York",
  "hours": [
    { "day_of_week": "monday", "opens": "09:00", "closes": "17:00" },
    { "day_of_week": "monday", "opens": "18:00", "closes": "22:00" },
    { "day_of_week": "friday", "opens": "22:00", "closes": "02:00" }
  ],
  "exception_hours": [
    {
      "valid_from": "2026-12-24",
      "valid_through": "2026-12-24",
      "opens": "09:00",
      "closes": "14:00"
    },
    {
      "valid_from": "2026-12-25",
      "valid_through": "2026-12-25"
    }
  ]
}

The contract is compact: each entry describes one open interval; repeated entries for the same day represent split shifts; a closes value earlier than opens spans midnight; and a date-bounded exception without opens means closed for that period. timezone supplies the interpretation context for local times. The example adapts Schema.org's semantics to UCP's snake_case naming and HH:MM convention rather than copying its JSON-LD representation verbatim.

Is there a concrete requirement that OpeningHoursSpecification cannot model? If not, I would align to it and remove the custom closed/24-hour flags, precedence rules, and overnight splitting convention.

4. Is offerings.inventory.quantity an inventory-disclosure query?

The store-finder use case—"which nearby location can fulfill the item I need?"—is valuable. A hard minimum quantity filter, however, lets a caller repeatedly probe thresholds and approximate a store's stock level even when the response never returns a count.

I suggest framing this as Buyer demand and coarse availability, not inventory disclosure:

• reuse UCP's existing availability semantics rather than parallel inventory concept;
• treat requested quantity as intent that a Business may coarsen;
• change language to not imply that exact on-hand counts are returned;

5. What does offerings mean? 😅

Modelled request can filter on:

{
  "offerings": {
    "amenities": ["..."],
    "inventory": [{ "id": "..." }]
  }
}

The standardized Location entity, however, exposes neither amenities nor offerings. Although the filter contract implies that each returned Location satisfies the requested values, a Platform cannot render the matched facts, inspect additional amenities, or present structured item availability from the response without relying on vendor-defined fields. There is also a category question: amenities are relatively static Location characteristics, while item availability is dynamic and tied to another Catalog or menu identity. Grouping both under offerings may be convenient structurally, but does not necessarily make them one semantic concept.

My inclination would be to put static amenities on Location, model dynamic availability separately using the existing UCP availability vocabulary, and flatten the filter unless offerings gains a clearer cross-vertical contract.

6. What amenity vocabulary is interoperable across Businesses and verticals?

An open string is the right wire type for UCP, but the current proposal defines no well-known values. Should UCP publish a small open vocabulary for interoperable matching, and which initial values are important enough to standardize?

7. What are the capability-specific security and privacy requirements?

Location handles Buyer location hints, enumerates physical sites, describes service coverage, and can be used to probe per-location item availability. The generic Signals reference and current privacy note do not cover those capability-specific risks.

I think the specification needs explicit Security and Privacy Considerations covering:

• coarse-by-default Buyer location and progressive disclosure;
• purpose limitation and retention of location inputs;
• store/site enumeration and rate limiting;
• inventory and availability probing;
• disclosure of internal, private, or non-buyer-visible locations;
• disclosure of precise service-area geometry.

8. What is the bounded Location projection for Catalog and Checkout?

This PR points Checkout’s pickup destination directly at the rich common Location entity. That couples Checkout to the complete Location discovery model: geo, hours, service area, amenities, and every future Location extension would automatically accrete into the transactional response. I don't think that's right.

In Catalog Fulfillment (#507), we deliberately introduced a thin Location projection: a stable location ID plus method description. This avoided embedding an N-store matrix in product results and deferred richer Location facts to a separately negotiated capability. That boundary still makes sense, but I think there is a middle ground: split Location into a bounded base and an extended discovery entity.

Base Location
  id
  name
  address?
      │
      └── allOf → Extended Location
                    geo
                    hours
                    exception_hours
                    timezone
                    amenities
                    service_area

Catalog and Checkout would use the bounded, buyer-renderable base. Location Search/Lookup would return the extended entity when the service is negotiated. Platform requests would select a Location by stable id rather than asserting Business-owned name/address facts. This preserves the bounded Catalog model from #507, keeps Catalog and Checkout independently renderable, and prevents the full Location discovery model from accreting into every Checkout response.

[amithanda]

+1 on scoping the service to dev.ucp.common.location. The thing that pushes me here is what the profile can still express once common has more than one domain in it, since the service key is what determines how many endpoints and how many version trains a business gets.

The setup. Suppose common grows the way the name invites, say Location plus Reviews plus Identity linking. Under a catch-all service the profile can only say:

"services": {
  "dev.ucp.common": [{
    "version": "2026-04-08",
    "transport": "rest",
    "schema": ".../services/common/rest.openapi.json",
    "endpoint": "https://business.example.com/ucp"
  }]
}

One endpoint, one transport document, and one version covering store lookup, review retrieval, and identity linking. That seems to make three fairly ordinary deployments unexpressible:

1. Routing. Store locator data is usually served by the merchant's own site infrastructure, while reviews are very often served by a third-party review platform on that vendor's domain, and identity linking sits behind the IdP. With one endpoint per transport per service there is no way to say that. The workaround would be a per-capability endpoint override, which is scoped services under a different name.
2. Versioning. The service entry carries its own version. A Reviews field change bumps the shared service version and emits a churn signal to every Location implementer even though nothing about Location moved. Domains that are operated by different parties rarely share a release cadence.
3. Operational policy. A public store locator is anonymous, cacheable, and high volume. Identity linking handles tokens and wants stricter auth and tighter rate limits. One base URL for both forces a single shared policy, or path-based policy that the spec does not describe.

The scoped form expresses all three directly, including the case where two domains happen to share a host:

"services": {
  "dev.ucp.common.location": [{
    "version": "2026-04-08", "transport": "rest",
    "schema": ".../services/common/location/rest.openapi.json",
    "endpoint": "https://stores.business.example.com/ucp"
  }],
  "dev.ucp.common.reviews": [{
    "version": "2026-01-11", "transport": "rest",
    "schema": ".../services/common/reviews/rest.openapi.json",
    "endpoint": "https://ucp.reviews-vendor.example.com/business-123"
  }],
  "dev.ucp.common.identity": [{
    "version": "2026-04-08", "transport": "rest",
    "schema": ".../services/common/identity/rest.openapi.json",
    "endpoint": "https://business.example.com/ucp"
  }]
}

The asymmetry I think settles it: scoped services can emulate the catch-all, but the catch-all cannot emulate scoped. A business serving everything from one gateway just points every scoped entry at the same endpoint, as Identity does above, and pays a few redundant lines of generated JSON. A business that needs reviews served by a vendor and locations served in-house has no move available under the catch-all until the spec itself changes. Where one option is a strict superset of the other in expressive power and the only cost is profile verbosity, is verbosity not the cheaper thing to pay? Profile JSON is generated and fetched once, while endpoint topology is a deployment constraint that cannot be refactored away.

Would it be worth writing the rule down explicitly, something like: a service is the unit of deployment, not the unit of naming? A new service is warranted whenever a domain could plausibly be operated by a different party, on different infrastructure, or on a different release cadence than its siblings.

I like that framing because it explains the existing corpus rather than contradicting it. dev.ucp.shopping stays one service correctly, since cart, catalog, checkout, and orders share a transactional session and one commerce backend, so the cohesion is real. dev.ucp.common fails that test close to by construction, since "common" is defined as whatever is cross-vertical, which is nearly the opposite of a deployment boundary. On that reading the Catalog precedent this PR follows is not being overturned, just scoped: Catalog rides the shopping service because shopping is cohesive, not because "one service per namespace" is the rule. common looks like the first namespace where naming and deployment come apart, which is why it seems worth deciding deliberately rather than inheriting the Catalog shape by default.

[amithanda]

For suggestion 2. above could we just drop the circle instead of upgrading it to polygons?

geofence_radius only appears in one place that matters, the Location response. Both filter inputs (distance.center and geofence_point) send just a point, as the rest.md examples show. And geofence_point is a predicate the Business evaluates server side, so it behaves identically whether coverage is a circle, a polygon, a postal code list, or a drive-time isochrone. The circle is only needed to publish the shape, never to ask the question.

That matters because publishing it as a circle is currently self-contradictory. search.md:96 binds the filter to the circle ("locations whose circular service area (defined by geofence_radius) contains the specified point"), so a Business whose real area is a polygon has to either approximate it (wrong answers near the boundary, across a river or a highway) or evaluate its true shape (in which case the published radius disagrees with the filter result). Which one is authoritative is undefined, as is the case where a location publishes no radius but a geofence_point filter arrives.

Proposal: drop geofence_radius and let coverage stay a server-evaluated predicate.

• geo.json becomes a pure point, which is all three call sites actually need;
• the filter takes an intent-based name such as serves or coverage, since the question is "which locations serve this?" rather than "whose circle contains this?";
• the spec says Businesses MAY evaluate coverage with any internal representation and MUST treat their own evaluation as authoritative, so presence in the result set is the answer and no geometry is returned;
• would it be worth accepting a postal address here too? index.md:27 frames the use case as coverage "for a buyer's address," but the filter takes only latitude and longitude, so postal-code-based Businesses have to reverse geocode back into the ZIP they already reason in.

Why this looks better than adding Polygon/MultiPolygon: it removes the contradiction rather than encoding it more precisely, it keeps the one representation every Business can implement, and it avoids publishing geometry that most would decline to share anyway.