COS stores
GET https://api.api.sh/cos/v1/stores
The COS store locator: stores in a country (or one city), or one store by its code, with address, phone, coordinates, store type and weekly opening hours with exceptions.
Every response includes credits_used: the credits this call cost.
Part of the COS API: 13 endpoints with prices, use cases and example responses.
Parameters
| name | type | description |
|---|---|---|
country | string | Country, two letters (see /cos/v1/store-countries). Example: GB |
city | string | Only this city (name as /cos/v1/store-cities lists it). |
city_id | string | City id from /cos/v1/store-cities, instead of city. |
store_code | string | One store by its code, e.g. US0888 (instead of country). |
language | string | Language of names, two letters (default en). |
Every endpoint also takes fresh, raw, fields (see lean responses and caching).
Example
curl "https://api.api.sh/cos/v1/stores?country=GB" \
-H "x-api-key: $APISH_KEY" import os, requests
res = requests.get(
"https://api.api.sh/cos/v1/stores",
params={"country": "GB"},
headers={"x-api-key": os.environ["APISH_KEY"]},
timeout=120,
)
res.raise_for_status()
data = res.json() const url = new URL("https://api.api.sh/cos/v1/stores");
url.searchParams.set("country", "GB");
const res = await fetch(url, { headers: { "x-api-key": process.env.APISH_KEY } });
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json(); Response
A JSON object with the fields described above, plus raw (the source's own data), cached, fetched_at and credits_used. Errors return {"success": false, "error": "…"} with the HTTP status (see errors). A lookup that ran but found nothing (404) costs the price above; refused calls and errors on our side are free (what's charged).
Example response (real call, trimmed: lists cut to 2 items, long text shortened, raw left out)
{"country": "GB","city": null,"city_id": null,"count": 18,"stores": [{"store_code": "GB0001","name": "Edinburgh","status": "OPEN","type": "Core +","address": "St James Quarter, 312-314 St James Square","city": "Edinburgh","state": null,"postcode": "EH1 3AE","country": "United Kingdom","country_code": "GB","phone": "+1 555 010 0000","latitude": 55.95511810048716,"longitude": -3.18832526212758,"opening_hours": [{"day": "Mon","opens": "09:00","closes": "20:00"},{"day": "Tue","opens": "09:00","closes": "20:00"},"… 5 more"],"opening_hour_exceptions": [],"opening_date": null,"closing_date": null},{"store_code": "GB0019","name": "Selfridges London","status": "OPEN","type": "Core +","address": "400 Oxford Street","city": "London","state": null,"postcode": "W1A 1AB","country": "United Kingdom","country_code": "GB","phone": "","latitude": 51.51454422415974,"longitude": -0.15299811793975,"opening_hours": [{"day": "Mon","opens": "10:00","closes": "22:00"},{"day": "Tue","opens": "10:00","closes": "22:00"},"… 5 more"],"opening_hour_exceptions": [],"opening_date": null,"closing_date": null},"… 16 more"],"cached": false,"credits_used": 1}The fastest way to see the full response is the playground: it runs this endpoint with your account and shows the exact JSON.