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

# Identify a record

> From a barcode, a code or an artist and title to the album, then to the exact pressing.

Identification happens in two steps. The API gets you to the **album** right away. Getting to the exact **pressing** is optional, and your app decides how far to go.

```mermaid theme={null}
flowchart LR
  B[Barcode] --> A[Album]
  T[Artist and title] --> A
  A -->|optional| F[Filter and facets]
  C[Catalog number or runout] --> X[Pressing]
  F --> X
```

## 1. Get the album

### Barcode (best)

Scan the barcode on the back. It's the most reliable input: 99.2% of Discogs vinyl barcodes belong to exactly one album, and 83.4% to exactly one pressing.

```bash theme={null}
curl "https://api.openvinyl.dev/v1/albums?barcode=0%2093624%2095217%206"
```

Pass the barcode as printed. Spaces, dashes and leading zeros don't matter, and UPC-12 and EAN-13 forms of the same code match each other.

The response's `match` field tells you what to do next:

| `match` | Meaning | Next step |
| - | - | - |
| `one_pressing` | Exactly one pressing has this barcode | Done |
| `one_album` | One album, several pressings | Stop at the album, or narrow (step 2) |
| `several_albums` | The barcode is shared by different albums (0.8% of barcodes) | Show the albums and let the user pick |
| `none` | Unknown barcode | Try artist and title, then consider a [contribution](https://docs.openvinyl.dev/guides/contributions.md) |

> [!TIP]
>
> Decode the barcode on the device (for example with the browser's `BarcodeDetector` API) and send only the digits. It's faster and no image leaves the phone.

### Artist and title

```bash theme={null}
curl "https://api.openvinyl.dev/v1/albums?q=jay-z%20blueprint"
```

Word order doesn't matter and "the" is ignored. Albums with many vinyl versions rank above one-off releases with similar names.

## 2. Narrow to the pressing

### With filters and facets

`GET /v1/albums/{id}/pressings` filters the album's pressings and returns `facets`: the count of each remaining value. Ask the user about the facet that splits the list best.

```bash theme={null}
curl "https://api.openvinyl.dev/v1/albums/m10362/pressings?country=US&label=Harvest&year=1973"
```

```json theme={null}
{
  "total": 29,
  "facets": {
    "plant": [
      { "value": "Capitol Records Pressing Plant, Jacksonville", "count": 11 },
      { "value": "Capitol Records Pressing Plant, Winchester", "count": 9 },
      { "value": "Capitol Records Pressing Plant, Los Angeles", "count": 5 }
    ],
    "format": [{ "value": "Stereo", "count": 10 }, { "value": "Repress", "count": 9 }]
  }
}
```

*The Dark Side of the Moon* goes from 674 pressings to 111 with `country=US`, then to 29 with `label=Harvest&year=1973`.

### With codes from the record

The runout etching (the text scratched into the vinyl near the label) is the strongest pressing identifier. Any fragment works:

```bash theme={null}
curl "https://api.openvinyl.dev/v1/search?runout=SMAS-1-11163%20F2"
```

`/v1/search` also takes `catno`, `barcode`, `label`, `country`, `artist`, `title` and `year`, and scores each candidate by which fields matched. When pressings tie, `note` says what would separate them.

### What separates tied pressings

In testing, pressings that tie on every code usually differ only in things no code captures: vinyl **color**, a limited edition, an insert, or the "Made in…" text on the back cover. Ask the user, or read it from a photo of the label.

## Example: four real records

| Record | Barcode result | Pressing decided by |
| - | - | - |
| The Flaming Lips, *Yoshimi Battles the Pink Robots* | `one_album`, 5 of 14 pressings | "Made in Canada" on the back cover |
| Twenty One Pilots, *More Than We Ever Imagined* | `one_pressing` | Barcode alone |
| Jay-Z / Linkin Park, *Collision Course* | `one_album`, 4 of 11 pressings | "Warner Bros. … Made in U.S.A." on the back, then the label |
| Arcade Fire, *The Suburbs* | `one_pressing` | Barcode alone (2017 reissue) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.