> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guppyapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Resolve

> Find canonical targets (products, venues, facilities) without passing URLs

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:

1. **Resolve** candidates (products / venues / facilities)
2. **Select** a candidate (user confirmation or programmatic choice)
3. **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

<ParamField body="query" type="string" required>
  Human-friendly query like "PS5 Pro" or a model name.
</ParamField>

<ParamField body="identifiers" type="object">
  Optional identifiers like GTIN/UPC/SKU.
</ParamField>

<ParamField body="allowed_merchants" type="array">
  Optional allowlist of merchants (e.g., `["target", "bestbuy", "walmart"]`).
</ParamField>

<ParamField body="limit" type="integer">
  Maximum number of candidates to return.
</ParamField>

### Example

```json theme={null}
{
  "query": "PS5 Pro",
  "allowed_merchants": ["target", "bestbuy", "walmart"],
  "limit": 5
}
```

### Response (example)

```json theme={null}
{
  "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

<ParamField body="query" type="string" required>
  Venue name or partial name (e.g., "Nopa").
</ParamField>

<ParamField body="location" type="object" required>
  Location constraint.
</ParamField>

<ParamField body="location.city" type="string">
  City name (recommended if you don't have lat/lng).
</ParamField>

<ParamField body="location.lat" type="number">
  Latitude for geo search.
</ParamField>

<ParamField body="location.lng" type="number">
  Longitude for geo search.
</ParamField>

<ParamField body="location.radius_miles" type="number">
  Search radius in miles (required for lat/lng searches).
</ParamField>

<ParamField body="allowed_providers" type="array">
  Optional allowlist (e.g., `["resy", "opentable"]`).
</ParamField>

### Example

```json theme={null}
{
  "query": "Nopa",
  "location": { "city": "San Francisco" },
  "allowed_providers": ["resy", "opentable"]
}
```

### Response (example)

```json theme={null}
{
  "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

<ParamField body="kind" type="string" required>
  Appointment kind (e.g., `passport`, `dmv`).
</ParamField>

<ParamField body="country" type="string">
  Country code (e.g., `US`).
</ParamField>

<ParamField body="location" type="object" required>
  Location constraint (geo or city/state).
</ParamField>

<ParamField body="location.lat" type="number">
  Latitude.
</ParamField>

<ParamField body="location.lng" type="number">
  Longitude.
</ParamField>

<ParamField body="location.radius_miles" type="number">
  Radius in miles.
</ParamField>

<ParamField body="allowed_providers" type="array">
  Optional allowlist of providers relevant to the kind (varies by region).
</ParamField>

### Example

```json theme={null}
{
  "kind": "passport",
  "country": "US",
  "location": { "lat": 37.7749, "lng": -122.4194, "radius_miles": 30 }
}
```

### Response (example)

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