Name: Drinks Intelligence API | Sourced Wine, Spirits & Beer Data
Brand: pinpointed
SKU: api-pinpointed-pinpointed
Availability: InStock
Author: API Market

Ian Carroll

# Pinpointed Drinks Intelligence API

## Drinks intelligence you can cite

Most "AI sommelier" tools are a general-purpose language model wrapped in a wine-themed prompt. Ask them a specific question about a Barolo's maximum yield, or the grape composition rules for a protected geographical indication, and they will produce a fluent, confident answer that may or may not be true. The Pinpointed Drinks Intelligence API (PDI) takes a different approach: every fact it returns is backed by a traceable source, and when the underlying evidence doesn't exist, the API says so explicitly instead of inventing an answer.

PDI is a structured HTTP API for wine, spirits, and beer applications. It was built to power Pinpointed's own AI Sommelier product for drinks retailers, and is now available as a standalone API for anyone building commerce, content, or research tools in the drinks space.

## What it does

PDI exposes four core calls that cover the common workflow for working with drinks entities:

- **`GET /v1/resolve-entity`** — Resolve free-text input (a canonical name, alias, style, or wine geography) to PDI's best-matching entities. Useful as a first step whenever you have unstructured or user-typed input ("chianti classico", "napa cab", "IPA") and need a canonical identity to work with downstream.

- **`GET /v1/explain`** — Retrieve the full structured, source-aware profile PDI currently holds for an entity: production rules (grape composition, maximum yields, aging requirements), legal and regulatory context (EU GI framework references, national disciplinari, CELEX identifiers), and registration metadata (protection scheme, issuing authority, effective dates). Every claim carries a `provenance` block with a source locator, source hash, and evidence hash, so you can trace exactly where a fact came from and verify it hasn't been silently altered.

- **`GET /v1/pair`** — Get explainable pairing guidance grounded in sourced sensory evidence. If PDI doesn't yet have sufficient sourced sensory data for an entity, the response returns `pairing_available: false` with an explicit `reason` (e.g. `insufficient_sourced_sensory_data`) rather than a plausible-sounding guess.

- **`GET /v1/compare`** — Resolve two entities and return both profiles side by side, flagging whether they belong to the same PDI domain (e.g. two wine geographies) or are being compared across domains.

A lightweight `GET /health` endpoint reports upstream gateway and engine status. To track your own consumption, use your API.market [Monthly Usage](https://api.market/account/monthly-usage) page or the Analytics link on your subscription — that is the quota your plan is billed against.

## Knowledge boundaries, not invented answers

The defining design decision behind PDI is what it does *not* do: it does not paper over gaps in its evidence with fluent-sounding filler. Every response that touches sourced knowledge includes an explicit `knowledge_boundary` object stating what is and isn't covered — for example, distinguishing a generic EU legal framework rule from a geography-specific production fact, or making clear that a legal definition is not the same thing as a tasting note. If you've been burned by an LLM confidently hallucinating a wine region's yield limits or a spirit's legal definition, this is the API built specifically to not do that.

## Coverage

PDI's knowledge base currently spans:

- **Wine geographies** — Protected Designations of Origin (PDO) and Protected Geographical Indications (PGI), sourced from official registries such as the EU's eAmbrosia database and national production disciplinari (e.g. Italy's MASAF filings).
- **Grape varieties** — canonical identities and their relationships to wine geographies.
- **Spirits categories** — legal and production definitions.
- **Beer styles** — style resolution and available profile data.

Coverage is continuously expanding, and the API is explicit about the edges of what it currently knows — a query for a well-documented PDO like Barolo will return dense, richly sourced production and legal evidence; a less-documented style may return partial data or an explicit boundary flag instead of a confident guess.

## Example request

```bash
curl -H "x-api-market-key: $API_MARKET_KEY" \
  "https://prod.api.market/api/v1/pinpointed/pinpointed/v1/explain?q=Barolo"
```

Every endpoint follows the same pattern — append the endpoint path to the base URL and send your API.market key:

```bash
curl -H "x-api-market-key: $API_MARKET_KEY" \
  "https://prod.api.market/api/v1/pinpointed/pinpointed/v1/compare?left=Barolo&right=Barbaresco"
```

## Who this is for

- **Drinks e-commerce and retail platforms** wanting to surface accurate, sourced product information without maintaining their own legal/regulatory knowledge base.
- **AI agents and chatbots** in the food-and-drink space that need a factual grounding layer to cite rather than hallucinate.
- **Content and publishing tools** generating wine, spirits, or beer copy that needs to be legally and factually defensible.
- **Compliance and labeling tools** that need traceable, sourced answers to "is this claim accurate" questions.

## Response format

All endpoints return JSON. Successful responses include an `ok: true` field along with the resolved `domain` (`wine_geography`, `grape_variety`, `spirits_category`, or `beer_style`), resolution metadata, and the relevant structured payload. Error responses return `ok: false` with a machine-readable `error` code and human-readable `message`. Standard HTTP status codes are used throughout: `400` for invalid requests, `401` for authentication failures, `404` when an entity cannot be resolved, and `429` when rate or quota limits are reached.

## Authentication and plans

**Base URL**

```
https://prod.api.market/api/v1/pinpointed/pinpointed
```

**Authentication**

Every request must include your API.market key in the `x-api-market-key` header. No other key, token, or account is required — subscribe to a plan on this page and your key works straight away. You can find or create your key on the [API Keys](https://api.market/account/apiKeys) page.

| Header | Value |
| :--- | :--- |
| `x-api-market-key` | Your API.market API key |

**Plans**

| Plan | Price | Included API units | Limit type |
| :--- | :--- | :--- | :--- |
| Free | $0 | 25 | Hard |
| Dev | $99/month | 2,500 | Hard |
| Pro | $299/month | 25,000 | Hard |

Every plan includes all endpoints. Hard limits mean requests stop once the included units are used, so you are never billed for overage. Unused units reset at the end of each billing cycle.

## Example response shape

A call to `/v1/resolve-entity?q=Barolo` returns a ranked list of candidate matches with a domain, match type, and match score, so your application can decide programmatically whether a match is confident enough to act on automatically or whether it should prompt the user to disambiguate:

```json
{
  "ok": true,
  "query": "Barolo",
  "count": 1,
  "results": [
    {
      "domain": "wine_geography",
      "entity_id": "809",
      "canonical_name": "Barolo",
      "match_type": "exact_canonical",
      "match_score": 100,
      "geography_type": "pdo",
      "jurisdiction": "EU",
      "registration_identifier": "EUGI00000004441",
      "regulatory_status": "current"
    }
  ]
}
```

From there, `/v1/explain` returns the deeper profile: production rules with their exact source text, a `provenance` block per claim (source locator, source hash, evidence hash), registration metadata such as issuing authority and effective date, and an explicit `knowledge_boundary` object describing what the response does and does not establish. Nothing in the payload is generated text — every claim traces back to a specific document.

## Frequently asked questions

**Does this API use a language model to generate its answers?**
No. PDI is a structured retrieval system over a curated evidence base, not a model generating text from a prompt. Where PDI does incorporate model-assisted extraction (for example, deterministic segmentation of long legal texts into individual rules), the output is still the sourced original text, not a paraphrase or summary.

**What happens when PDI doesn't know something?**
The API tells you. Rather than returning a plausible-sounding but unverified answer, endpoints like `/v1/pair` return an explicit `pairing_available: false` with a `reason` field, and `/v1/explain` and `/v1/compare` include `knowledge_boundary` flags describing exactly what is and isn't covered by the response. This is a deliberate design choice: false confidence is more dangerous than a clearly labeled gap.

**Can I try it before subscribing?**
Yes. Subscribe to the Free plan on this page for 25 API units at no cost and no card required, and call any endpoint with your API.market key to evaluate the real output before moving to a paid plan.

**What jurisdictions and languages does the evidence cover?**
Current coverage is strongest for EU-registered wine geographies (PDO/PGI), sourced from the EU's eAmbrosia registry, EUR-Lex regulations, and national production specifications (disciplinari) in their original language, alongside English-language legal framework text. Coverage of spirits and beer domains, and of non-EU jurisdictions, is expanding over time — the `knowledge_boundary` and `resolution.regulatory_status` fields let you detect the current scope programmatically rather than assuming.

**Is this suitable for consumer-facing product copy?**
Yes, with the usual caveat that any legal or regulatory claim you publish should be reviewed for your specific use case. Because every fact returned by PDI carries a traceable source, it's well suited to compliance-sensitive contexts — labeling, regulatory copy, or any place where "where did this claim come from" needs a real answer.

## Contact Us

If you have any questions or need support, you can reach out to us through the chat available on this page, or email us at hello@magicapi.com.


Evidence-backed wine, spirits and beer API. Entity resolution, sourced legal and production facts, pairing and comparisons with explicit knowledge boundaries.