# Breweries API
> Search, filter and locate breweries worldwide — a fast, clean wrapper over Open Brewery DB covering thousands of breweries across the US and beyond. Filter by city, state, country, name, postal code or brewery type (micro, nano, regional, brewpub, large, bar, contract and more), sort results nearest-first from any latitude/longitude, autocomplete brewery names for typeahead, pull random breweries, fetch a single brewery by id and read aggregate counts. Every endpoint accepts input via the query string or the request body and returns lean, predictable JSON with normalized address, coordinates, phone and website fields. Ideal for beer and travel apps, store locators, maps and directory features.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/beer-api/..."
```

## Pricing
- **Free** (Free) — 12,000 calls/Mo, 3 req/s
- **Basic** ($4/Mo) — 120,000 calls/Mo, 8 req/s
- **Pro** ($12/Mo) — 800,000 calls/Mo, 20 req/s
- **Mega** ($35/Mo) — 4,000,000 calls/Mo, 50 req/s

## Endpoints

### Breweries

#### `GET /v1/autocomplete` — Autocomplete brewery names

**Parameters:**
- `query` (query, required, string) — Partial name Example: `dog`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/beer-api/v1/autocomplete?query=dog"
```

#### `GET /v1/brewery` — Single brewery by id

**Parameters:**
- `id` (query, required, string) — Brewery UUID Example: `5128df48-79fc-4f0f-8b52-d06be54d0cec`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/beer-api/v1/brewery?id=5128df48-79fc-4f0f-8b52-d06be54d0cec"
```

#### `GET /v1/meta` — Aggregate counts

**Parameters:**
- `by_country` (query, optional, string) — Country Example: `united states`
- `by_state` (query, optional, string) — State Example: `california`
- `by_type` (query, optional, string) — Type Example: `micro`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/beer-api/v1/meta?by_country=united+states&by_state=california&by_type=micro"
```

#### `GET /v1/random` — Random breweries

**Parameters:**
- `size` (query, optional, string) — 1..10 (default 1) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/beer-api/v1/random?size=1"
```

#### `GET /v1/search` — Search & filter breweries

**Parameters:**
- `by_city` (query, optional, string) — City Example: `san diego`
- `by_state` (query, optional, string) — State/province Example: `california`
- `by_country` (query, optional, string) — Country Example: `united states`
- `by_type` (query, optional, string) — micro|nano|regional|brewpub|large|bar|contract|... Example: `micro`
- `by_name` (query, optional, string) — Name contains Example: `dog`
- `lat` (query, optional, string) — Latitude for nearest-first Example: `32.71`
- `lon` (query, optional, string) — Longitude for nearest-first Example: `-117.16`
- `per_page` (query, optional, string) — 1..50 (default 15) Example: `15`
- `page` (query, optional, string) — Page Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/beer-api/v1/search?by_city=san+diego&by_state=california&by_country=united+states&by_type=micro&by_name=dog&lat=32.71&lon=-117.16&per_page=15&page=1"
```


---
Marketplace page: https://www.oanor.com/api/beer-api
OpenAPI spec: https://www.oanor.com/api/beer-api/openapi.json