Documentation

Getting Started

Everything you need to go from zero to your first API response. Takes about 5 minutes.

Request API Access

The Data API is in controlled access during our beta period. Send an email to save@buyersmarket.app with the subject line Data API Access Request and include:

· Your name and organisation

· How you intend to use the data (research topic, app, report, etc.)

· The volume of requests you expect per month

We respond within 1 business day. Academic and NGO use is free.

Authenticate

Every request must include your API key in the X-API-Key request header. Keep your key private — treat it like a password.

Request header

X-API-Key: bm_your_api_key_here

Security note: Never include your API key in client-side JavaScript or commit it to version control. Use environment variables or a secrets manager.

Make Your First Request

Let's fetch the current price of milk across all Jamaican supermarkets.

curl "https://data.buyersmarket.app/v1/prices?q=milk&limit=5" \
  -H "X-API-Key: bm_your_api_key_here"

import httpx

resp = httpx.get(
    "https://data.buyersmarket.app/v1/prices",
    params={"q": "milk", "limit": 5},
    headers={"X-API-Key": "bm_your_api_key_here"},
)
resp.raise_for_status()
print(resp.json())

const res = await fetch(
  "https://data.buyersmarket.app/v1/prices?q=milk&limit=5",
  { headers: { "X-API-Key": "bm_your_api_key_here" } }
);
const json = await res.json();
console.log(json);

HTTP 200 · application/json

{
  "data": [
    {
      "id": "a3f21bc8-...",
      "product_name": "Grace Full Cream Milk 1L",
      "barcode": "054871000123",
      "brand": "Grace",
      "category": "Dairy",
      "price_jmd": 425.00,
      "store_name": "Hi-Lo Food Stores",
      "chain_name": "Hi-Lo",
      "rating": "A",
      "scraped_at": "2026-03-03T06:14:00Z"
    }
  ],
  "total": 84,
  "page": 1,
  "page_size": 5,
  "has_next": true
}

Filter & Paginate

Every list endpoint supports filtering and pagination via query parameters.

Common filters

Parameter	Type	Description	Example
q	string	Full-text product search	?q=milk
category	string	Product category	?category=Dairy
store_id	UUID	Filter by store	?store_id=abc123
rating	A, B, or C	Price rating filter	?rating=A
limit	int (1–1000)	Results per page	?limit=100
offset	int	Skip N results (pagination)	?offset=100

Example: all dairy products rated A, page 2

curl "https://data.buyersmarket.app/v1/prices?category=Dairy&rating=A&limit=50&offset=50" \
  -H "X-API-Key: bm_your_api_key_here"

Understand Credits & Quotas

Every API request costs credits. Check your remaining quota in the response headers.

Header	Description
X-Quota-Limit	Your total monthly credit allowance
X-Quota-Used	Credits consumed so far this month

Standard endpoints

credit per request

Trend/history

credits per request

BGPI index

credit per request

Handle Errors

The API uses standard HTTP status codes. All error responses include a detail field.

Status	Meaning	Action
200	Success	—
401	Invalid or missing API key	Check your `X-API-Key` header
403	Key inactive or revoked	Contact support
422	Invalid query parameter	Check parameter names and types
429	Quota exhausted	Wait until next month or upgrade
500	Server error	Retry with exponential backoff

Error response body

{
  "detail": "API key not found or inactive."
}

Full SDK Examples

There's no official SDK yet — the REST API is simple enough that you only need an HTTP client. Here are idiomatic examples in common languages.

Python (httpx)

import httpx

BASE = "https://data.buyersmarket.app"
HEADERS = {"X-API-Key": "bm_your_api_key_here"}

with httpx.Client(base_url=BASE, headers=HEADERS) as client:
    # Get all dairy prices rated A
    resp = client.get("/v1/prices", params={"category": "Dairy", "rating": "A"})
    resp.raise_for_status()
    dairy = resp.json()["data"]

    # Get the BGPI index
    bgpi = client.get("/v1/market/bgpi").json()
    print(f"BGPI: {bgpi['index_value']} ({bgpi['date']})")

Python (requests)

import requests

SESSION = requests.Session()
SESSION.headers["X-API-Key"] = "bm_your_api_key_here"

r = SESSION.get(
    "https://data.buyersmarket.app/v1/prices",
    params={"category": "Produce", "limit": 100},
)
r.raise_for_status()
print(r.json()["data"])

Node.js (fetch)

const API_KEY = process.env.BM_API_KEY;
const BASE = "https://data.buyersmarket.app";

async function getPrices(params = {}) {
  const url = new URL("/v1/prices", BASE);
  Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
  const res = await fetch(url, {
    headers: { "X-API-Key": API_KEY },
  });
  if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
  return res.json();
}

const dairy = await getPrices({ category: "Dairy", limit: 50 });
console.log(dairy.data);

Need help? Email save@buyersmarket.app — we're happy to assist with integrations.