# Untappd Search ## Overview | Property | Value | |----------|-------| | **Status** | active | | **Method** | `GET` | | **Endpoint** | `/v2/untappd/search` | | **Base URL** | `https://api.piloterr.com` | | **Credit Cost** | 2 credits per call | | **Documentation** | https://www.piloterr.com/library/untappd-search | ## Description Search Untappd beers by keyword. Cards include brewery, ABV, and IBU. next is null when Untappd does not expose a next page. ## Authentication - **Key Name:** `x-api-key` - **Location:** HTTP Header - **Get an API key:** https://app.piloterr.com/register ## Example Request ```bash curl --location --request GET 'https://api.piloterr.com/v2/untappd/search' \ --header 'Content-Type: application/json' \ --header 'x-api-key: YOUR_API_KEY' ``` ## Example Response ### Lagunitas IPA ```json { "results": [ { "id": "4509", "abv": 6.2, "ibu": 51, "url": "https://untappd.com/b/lagunitas-brewing-company-ipa/4509", "name": "IPA", "image": "https://assets.untappd.com/site/beer_logos/beer-4509_21190_sm.jpeg", "style": "IPA - American", "rating": 3.68, "brewery": "Lagunitas Brewing Company", "abv_display": "6.2% ABV", "brewery_url": "https://untappd.com/brewery/765", "ibu_display": "51 IBU" } ], "pagination": { "next": null, "page": 1, "per_page": 5, "total_pages": null, "total_results": 401027 } } ``` ## Documentation ## Overview Search beers on Untappd. Send a keyword such as `ipa` or `stout`, or a search URL whose path is `/search`. The response is `{ results, pagination }` for the beer cards in the rendered results. Pass `results[].id` or `results[].url` to `/v2/untappd/beer`. Each card can include brewery, style, ABV, and IBU. `abv` is the number inside `abv_display` (for example `6.2` and `6.2% ABV`). `ibu` is the number inside `ibu_display` (for example `51` and `51 IBU`). ## Quickstart ``` GET https://api.piloterr.com/v2/untappd/search?query=ipa GET https://api.piloterr.com/v2/untappd/search?query=stout ``` GET and POST take the same `query`. `ipa` includes beer `4509`, name `IPA`, brewery Lagunitas Brewing Company, ABV `6.2`, IBU `51`. The beer call for `4509` returns that same id, name, brewery, ABV, and IBU. `stout` includes Guinness Draught, id `4473`. ## Parameters | Parameter | Required | Example | |---|---|---| | `query` | yes | `ipa` | `query` is required. A URL must be on `untappd.com` and its path must be `/search`. A beer URL belongs on the beer endpoint. Another host returns 400. There is no `page` parameter. ## Pagination Untappd prints a drink count and loads more hits inside the page. This endpoint returns the cards present in the fetch. `pagination.page` is `1`. `pagination.next` is `null` when the page does not expose a next URL. Do not invent one. `pagination.per_page` is the number of beer cards parsed, `5` for `ipa` and for `stout`. `pagination.total_results` is the drink count in the search stats, such as the six-digit count on `ipa`. `pagination.total_pages` is `null`. Ids are unique on the page. `next` stays `null` for these keyword searches because the site does not print a next page link. ## Response fields | Field | Type | Meaning | |---|---|---| | `results[].id` | string | Beer id, such as `4509` | | `results[].name` | string | Beer name | | `results[].url` | string | Beer URL, usually under `/b/` | | `results[].brewery` | string or null | Brewery | | `results[].brewery_url` | string or null | Brewery URL | | `results[].style` | string or null | Style | | `results[].abv` | number or null | ABV | | `results[].abv_display` | string or null | Printed ABV, such as `6.2% ABV` | | `results[].ibu` | number or null | IBU | | `results[].ibu_display` | string or null | Printed IBU, such as `51 IBU` | | `results[].rating` | number or null | Rating shown on the card. The beer page can print more decimal places | | `results[].image` | string or null | Label image | | `pagination.page` | integer | `1` | | `pagination.per_page` | integer or null | Cards returned | | `pagination.total_results` | number or null | Drink count Untappd prints | | `pagination.total_pages` | null | No page count | | `pagination.next` | null | No next URL on these searches | ## Use cases - Find Lagunitas IPA as id `4509` from the keyword `ipa`, with ABV `6.2` and IBU `51` on the card. - Compare ABV and IBU across the first `stout` cards, including Guinness Draught `4473`. - Keep `total_results` as the printed drink count and stop when `next` is `null`. ## Error codes | Code | Meaning | |---|---| | `400` | Empty query, a non-search URL, or a domain outside untappd.com | | `401` | Missing API key | | `404` | The page was not a beer search | | `500` | The fetch failed | ## Related endpoints [Untappd Beer](https://www.piloterr.com/library/untappd-beer)