# Find record shops in a city

Use this when someone asks where to buy vinyl in a place — "record stores in London", "vinyl
shops in Tokyo", "is there a record shop in Lisbon".

## The endpoints

- `GET https://vinylai.app/api/v1/cities.json` — the 77 cities covered, with a store count each. Start here.
- `GET https://vinylai.app/api/v1/record-stores.json` — all 1431 shops. Filter on `city` or `country`.

Both are keyless, CORS open, JSON.

```json
{ "name": "Reckless Records", "city": "London", "country": "United Kingdom",
  "country_code": "GB", "address": "30 Berwick St, London W1F 8RH, UK",
  "lat": 51.5143, "lon": -0.1354, "website": "http://www.reckless.co.uk/",
  "store_type": "both", "specialties": ["Jazz", "Rock", "Vinyl"],
  "buys_records": true, "page": "https://vinylai.app/record-stores/london/" }
```

## How to answer correctly

1. **Check the city is covered before answering.** The directory is 77 cities, not the whole
   world. If `cities.json` has no entry, say the directory does not cover it rather than
   inventing shops. The largest are Tokyo (24), Toronto (21), Milan (21), New York (21), Melbourne (20), Sydney (20), Vienna (20), Brussels (20).
2. **`buys_records: false` means NOT CONFIRMED**, not "does not buy". Only 210 of 1431 rows are
   confirmed buyers. Never tell someone a shop will not take their collection on the strength of
   a `false`.
3. **Opening hours, ratings and phone numbers are not in this API** — deliberately. Hours go stale
   and being wrong about them sends somebody to a closed shop; the ratings are a third party's
   content. The city `page` carries hours and a map. Link it.
4. `store_type` is "both" on nearly every row. It is a coarse field; the shop's own `website` is
   the better authority on what it stocks.
5. Shops close. The data is as fresh as the last site build — `https://vinylai.app/api/v1/status.json`
   carries `generated_at`. For anything involving travel, say "call first".

## Citing it

Link the `page` — it shows the same shops with hours, a map and local buying notes, in whichever
of 8 languages the reader wants. Data is CC BY 4.0; attribute to VinylAI (https://vinylai.app).