Resolve - Guppy

Guppy is not URL-driven. Instead, partners use Resolve endpoints to turn human-friendly input (names, locations, constraints) into canonical IDs that Guppy can reliably execute against. The standard integration pattern is:

Resolve candidates (products / venues / facilities)
Select a candidate (user confirmation or programmatic choice)
Create an intent referencing the canonical ID (e.g., product_id, venue_id, facility_id)

Resolve a product

POST /resolve/products Return canonical product candidates (optionally across multiple merchants).

Request Body

string

required

Human-friendly query like “PS5 Pro” or a model name.

object

Optional identifiers like GTIN/UPC/SKU.

array

Optional allowlist of merchants (e.g., ["target", "bestbuy", "walmart"]).

integer

Maximum number of candidates to return.

Example

{
  "query": "PS5 Pro",
  "allowed_merchants": ["target", "bestbuy", "walmart"],
  "limit": 5
}

Response (example)

{
  "candidates": [
    {
      "product_id": "prod_ps5pro_us_001",
      "name": "PlayStation 5 Pro Console",
      "identifiers": { "gtin": "…" },
      "merchant_coverage": ["target", "bestbuy", "walmart"]
    }
  ]
}

Resolve a restaurant/venue

POST /resolve/venues Return canonical venue candidates for reservations.

Request Body

string

required

Venue name or partial name (e.g., “Nopa”).

object

required

Location constraint.

string

City name (recommended if you don’t have lat/lng).

number

Latitude for geo search.

number

Longitude for geo search.

number

Search radius in miles (required for lat/lng searches).

array

Optional allowlist (e.g., ["resy", "opentable"]).

Example

{
  "query": "Nopa",
  "location": { "city": "San Francisco" },
  "allowed_providers": ["resy", "opentable"]
}

Response (example)

{
  "candidates": [
    {
      "venue_id": "ven_sf_nopa_001",
      "provider": "resy",
      "name": "Nopa",
      "address": "…",
      "city": "San Francisco"
    }
  ]
}

Resolve an appointment facility

POST /resolve/appointment-facilities Return canonical facilities for appointment-based intents (passport, DMV, etc.).

Request Body

string

required

Appointment kind (e.g., passport, dmv).

string

Country code (e.g., US).

object

required

Location constraint (geo or city/state).

number

Latitude.

number

Longitude.

number

Radius in miles.

array

Optional allowlist of providers relevant to the kind (varies by region).

Example

{
  "kind": "passport",
  "country": "US",
  "location": { "lat": 37.7749, "lng": -122.4194, "radius_miles": 30 }
}

Response (example)

{
  "candidates": [
    {
      "facility_id": "fac_us_passport_sf_003",
      "name": "USPS – Main Post Office",
      "address": "…",
      "provider": "usps"
    }
  ]
}

​Resolve a product

​Request Body

​Example

​Response (example)

​Resolve a restaurant/venue

​Request Body

​Example

​Response (example)

​Resolve an appointment facility

​Request Body

​Example

​Response (example)

Resolve a product

Request Body

Example

Response (example)

Resolve a restaurant/venue

Request Body

Example

Response (example)

Resolve an appointment facility

Request Body

Example

Response (example)