Markets

Endpoints

GET/v1/brands/{brand}/locations
GET/v1/brands/{brand}/markets

The Market object

Attributes

idstring
Unique identifier of the object (prefixed, opaque).
objectstring
market
brandstring
The brand the object belongs to (br_…).
codestring
ISO 3166-1 alpha-2, e.g. FR — the market parameter of the other endpoints.
languagestring
currencystring
statusenum
Lifecycle of a brand market, as shown by the navbar market chips. - active → sampled every cycle, selectable everywhere. - backfill → just activated, history being rebuilt; selectable, flagged. - off → detected (Shopify Markets…) but not activated; greyed out.
Possible values: active · backfill · off
sourceenum
Where a brand market comes from: detected in the connected store (Shopify Markets) or added by hand on « Catalogue · Marchés ».
Possible values: shopify · manual
domainstringnullable
localityobjectnullable
Show child attributes
- citystring
- regionstringnullable
- addressstringnullable
- phonestringnullable
- opening_hoursstringnullable
is_primaryboolean
activated_atstringnullable
livemodeboolean
true for live data, false for the test-mode sandbox.
createdinteger
Time at which the object was created (unix timestamp, seconds).

The Market object


{
  "id": "mkt_034oH7bZpQA7N8R6s421Ry",
  "object": "market",
  "brand": "br_034CyfRFSXUqzrbzV6MAfZ",
  "code": "string",
  "language": "fr",
  "currency": "EUR",
  "status": "active",
  "source": "shopify",
  "domain": "string",
  "locality": {
    "city": "string",
    "region": "string",
    "address": "string",
    "phone": "string",
    "opening_hours": "string"
  },
  "is_primary": true,
  "activated_at": "2026-09-21T02:40:00Z",
  "livemode": true,
  "created": 1790000000
}

The Location object

Attributes

idstring
Unique identifier of the object (prefixed, opaque).
objectstring
location
brandstring
The brand the object belongs to (br_…).
marketstring
The market's ISO 3166-1 alpha-2 code, e.g. FR.
namestring
citystring
regionstringnullable
postal_codestringnullable
addressstringnullable
phonestringnullable
opening_hoursstringnullable
urlstringnullable
sourceenum
Where an establishment row came from: read on the brand's site, or typed by an editor.
Possible values: site · manual
trackedboolean
Whether the query panel writes queries for it.
livemodeboolean
true for live data, false for the test-mode sandbox.
createdinteger
Time at which the object was created (unix timestamp, seconds).

The Location object


{
  "id": "loc_0342TwLkZ7AlSAO7Ctrcpb",
  "object": "location",
  "brand": "br_034CyfRFSXUqzrbzV6MAfZ",
  "market": "FR",
  "name": "Nordvelo",
  "city": "string",
  "region": "string",
  "postal_code": "string",
  "address": "string",
  "phone": "string",
  "opening_hours": "string",
  "url": "https://hooks.example.com/skoup",
  "source": "site",
  "tracked": true,
  "livemode": true,
  "created": 1790000000
}

List establishments

GET/v1/brands/{brand}/locations

The establishments of a local brand (a chain of practices, stores or agencies is one brand with many establishments). Empty for a brand that sells online. Queries, mentions and wrong-address alerts point at the establishment they are about.

Parameters

brandstringrequired
Brand id (br_…).
marketstring
trackedboolean
limitinteger
Number of objects to return, between 1 and 100 (default 20).
starting_afterstring
Cursor: the id of the last object of the previous page.

Returns

A dictionary with a data property holding up to limit location objects, newest first, and has_more telling whether another page exists. Raises an error if something goes wrong.

curl


curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/locations?limit=3 \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/locations?limit=3', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
  },
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('GET', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/locations?limit=3', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.get(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/locations?limit=3",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Response


{
  "object": "list",
  "url": "/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/locations",
  "has_more": false,
  "data": [
    {
      "id": "loc_0342TwLkZ7AlSAO7Ctrcpb",
      "object": "location",
      "brand": "br_034CyfRFSXUqzrbzV6MAfZ",
      "market": "FR",
      "name": "Nordvelo",
      "city": "string",
      "region": "string",
      "postal_code": "string",
      "address": "string",
      "phone": "string",
      "opening_hours": "string",
      "url": "https://hooks.example.com/skoup",
      "source": "site",
      "tracked": true,
      "livemode": true,
      "created": 1790000000
    }
  ]
}

List markets

GET/v1/brands/{brand}/markets

The country markets of a brand. Measurements are per market: pass a market code (e.g. FR) to the endpoints that take a market.