Markets

Endpoints

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

L’objet Market

Attributs

idstring
Identifiant unique de l'objet (préfixé, opaque).
objectstring
market
brandstring
La marque à laquelle l'objet appartient (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.
Valeurs possibles : 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 ».
Valeurs possibles : shopify · manual
domainstringnullable
localityobjectnullable
Afficher les attributs enfants
- citystring
- regionstringnullable
- addressstringnullable
- phonestringnullable
- opening_hoursstringnullable
is_primaryboolean
activated_atstringnullable
livemodeboolean
true pour les données réelles, false pour le bac à sable du mode test.
createdinteger
Time at which the object was created (unix timestamp, seconds).

L'objet Market


{
  "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
}

L’objet Location

Attributs

idstring
Identifiant unique de l'objet (préfixé, opaque).
objectstring
location
brandstring
La marque à laquelle l'objet appartient (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.
Valeurs possibles : site · manual
trackedboolean
Whether the query panel writes queries for it.
livemodeboolean
true pour les données réelles, false pour le bac à sable du mode test.
createdinteger
Time at which the object was created (unix timestamp, seconds).

L'objet Location


{
  "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.

Paramètres

brandstringobligatoire
Brand id (br_…).
marketstring
trackedboolean
limitinteger
Nombre d'objets à renvoyer, entre 1 et 100 (20 par défaut).
starting_afterstring
Curseur : l'id du dernier objet de la page précédente.

Retour

Un dictionnaire dont la propriété data contient jusqu’à limit objets location, du plus récent au plus ancien, et has_more indique s’il reste une page. Lève une erreur en cas de problème.

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()

Réponse


{
  "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.