How to Manage Thousands of Business Locations via API

curl "https://ai.synup.com/api/v1/locations?clientId=CLIENT_ID&limit=200" \
  -H "Authorization: Bearer $SYNUP_API_KEY"
# then, with the nextCursor from the response:
curl "https://ai.synup.com/api/v1/locations?clientId=CLIENT_ID&limit=200&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer $SYNUP_API_KEY"

const API = "https://ai.synup.com/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.SYNUP_API_KEY}`,
  "Content-Type": "application/json",
};

async function* allLocations(clientId) {
  let cursor = "";
  do {
    const params = new URLSearchParams({ clientId, limit: "200", cursor });
    const res = await fetch(`${API}/locations?${params}`, { headers });
    if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
    const { data } = await res.json();
    yield* data.locations;
    cursor = data.nextCursor ?? "";
  } while (cursor);
}

async function idMap(clientId) {
  const map = new Map(); // storeCode -> Synup location row
  for await (const row of allLocations(clientId)) {
    if (row.storeCode) map.set(row.storeCode, row);
  }
  return map;
}

import os
import requests

API = "https://ai.synup.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SYNUP_API_KEY']}"}

def all_locations(client_id):
    cursor = ""
    while True:
        r = requests.get(f"{API}/locations", headers=HEADERS, timeout=30,
                         params={"clientId": client_id, "limit": 200, "cursor": cursor})
        r.raise_for_status()
        data = r.json()["data"]
        yield from data["locations"]
        cursor = data.get("nextCursor") or ""
        if not cursor:
            return

def id_map(client_id):
    return {row["storeCode"]: row for row in all_locations(client_id) if row.get("storeCode")}

curl -X POST https://ai.synup.com/api/v1/locations/tags \
  -H "Authorization: Bearer $SYNUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "clientId": "CLIENT_ID", "name": "region:west" }'

curl -X POST https://ai.synup.com/api/v1/locations/tags/TAG_ID/locations \
  -H "Authorization: Bearer $SYNUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "locationIds": ["LOC_1", "LOC_2", "LOC_3"] }'

async function tagLocations(clientId, name, locationIds) {
  const created = await fetch(`${API}/locations/tags`, {
    method: "POST",
    headers,
    body: JSON.stringify({ clientId, name }),
  });
  if (!created.ok) throw new Error(`${created.status}: ${(await created.json()).error}`);
  const { data: tag } = await created.json();

  const applied = await fetch(`${API}/locations/tags/${tag.id}/locations`, {
    method: "POST",
    headers,
    body: JSON.stringify({ locationIds }),
  });
  if (!applied.ok) throw new Error(`${applied.status}: ${(await applied.json()).error}`);
  return (await applied.json()).data; // { added: [...], skipped: [...] }
}

def tag_locations(client_id, name, location_ids):
    r = requests.post(f"{API}/locations/tags", headers=HEADERS, timeout=30,
                      json={"clientId": client_id, "name": name})
    r.raise_for_status()
    tag = r.json()["data"]
    r = requests.post(f"{API}/locations/tags/{tag['id']}/locations", headers=HEADERS, timeout=30,
                      json={"locationIds": location_ids})
    r.raise_for_status()
    return r.json()["data"]  # {"added": [...], "skipped": [...]}

# Shell scripts do not pool well. Use the JavaScript or Python worker, or
# run a batch tool that honours Retry-After. A single retrying call looks like:
until curl -s -o /tmp/out.json -w "%{http_code}" -X PATCH https://ai.synup.com/api/v1/locations/LOCATION_ID \
  -H "Authorization: Bearer $SYNUP_API_KEY" -H "Content-Type: application/json" \
  -d '{ "phone": "+1 415 555 0199" }' | grep -qv 429; do
  sleep 5
done

async function request(path, init, attempt = 0) {
  const res = await fetch(`${API}${path}`, { ...init, headers });
  if (res.status === 429 && attempt < 6) {
    const wait = Number(res.headers.get("retry-after") ?? 2 ** attempt);
    await new Promise((r) => setTimeout(r, wait * 1000));
    return request(path, init, attempt + 1);
  }
  if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
  return (await res.json()).data;
}

async function pool(items, worker, concurrency = 4) {
  const results = [];
  let next = 0;
  await Promise.all(
    Array.from({ length: concurrency }, async () => {
      while (next < items.length) {
        const item = items[next++];
        try {
          results.push({ item, ok: true, value: await worker(item) });
        } catch (error) {
          results.push({ item, ok: false, error: String(error) });
        }
      }
    })
  );
  return results;
}

// changes: [{ locationId, patch }]
const outcome = await pool(changes, ({ locationId, patch }) =>
  request(`/locations/${locationId}`, { method: "PATCH", body: JSON.stringify(patch) })
);
console.log(`${outcome.filter((r) => r.ok).length} updated, ${outcome.filter((r) => !r.ok).length} failed`);

import time
from concurrent.futures import ThreadPoolExecutor

def request(method, path, json=None, attempt=0):
    r = requests.request(method, f"{API}{path}", headers=HEADERS, json=json, timeout=30)
    if r.status_code == 429 and attempt < 6:
        wait = float(r.headers.get("Retry-After", 2 ** attempt))
        time.sleep(wait)
        return request(method, path, json, attempt + 1)
    r.raise_for_status()
    return r.json()["data"]

def apply(change):
    location_id, patch = change
    try:
        return {"locationId": location_id, "ok": True, "value": request("PATCH", f"/locations/{location_id}", patch)}
    except requests.HTTPError as e:
        return {"locationId": location_id, "ok": False, "error": e.response.text}

# changes: [(location_id, patch), ...]
with ThreadPoolExecutor(max_workers=4) as pool:
    outcome = list(pool.map(apply, changes))
print(f"{sum(r['ok'] for r in outcome)} updated, {sum(not r['ok'] for r in outcome)} failed")