Documentation

API Reference

Base URL: https://data.buyersmarket.app
All requests require the X-API-Key header. Responses are JSON.

GET Prices

/v1/prices

Current price observations scraped daily from Jamaican retailers. Each record represents one product at one store with its A-B-C rating. 1 credit per request.

Query parameters

Parameter	Type	Description
q	string	Full-text search on product name
product_id	UUID	Filter by specific product
store_id	UUID	Filter by specific store
category	string	Filter by product category (e.g. Dairy, Produce)
brand	string	Filter by brand name
rating	A \| B \| C	Filter by A-B-C price rating
min_price	number	Minimum price in JMD
max_price	number	Maximum price in JMD
limit	int (1–1000)	Results per page. Default: 50
offset	int	Pagination offset. Default: 0

Example

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

Response schema

{
  "data": [
    {
      "id": "uuid",
      "product_id": "uuid",
      "product_name": "string",
      "barcode": "string | null",
      "brand": "string | null",
      "category": "string",
      "price_jmd": 425.00,
      "store_id": "uuid",
      "store_name": "string",
      "chain_name": "string",
      "rating": "A | B | C | null",
      "scraped_at": "ISO 8601 datetime"
    }
  ],
  "total": 847,
  "page": 1,
  "page_size": 10,
  "has_next": true
}

GET Products

/v1/products · /v1/products/{id}

Browse or search the 18,000+ product catalog. Includes barcodes, brands, categories, and unit sizes. 1 credit per request.

Query parameters

Parameter	Type	Description
q	string	Full-text search
category	string	Category filter
brand	string	Brand filter
barcode	string	Exact barcode lookup (EAN-13 / UPC)
limit / offset	int	Pagination

Response schema

{
  "data": [
    {
      "id": "uuid",
      "name": "Grace Full Cream Milk 1L",
      "barcode": "054871000123",
      "brand": "Grace",
      "category": "Dairy",
      "subcategory": "Milk",
      "unit_size": 1.0,
      "unit_type": "litre",
      "image_url": "https://storage.googleapis.com/...",
      "created_at": "ISO 8601"
    }
  ],
  "total": 18302,
  "page": 1
}

GET Stores

/v1/stores · /v1/stores/{id}

List of 31 store locations across Jamaica with GPS coordinates and chain affiliation. 1 credit per request.

Response schema

{
  "data": [
    {
      "id": "uuid",
      "name": "Hi-Lo — Liguanea",
      "chain_id": "uuid",
      "chain_name": "Hi-Lo Food Stores",
      "address": "Liguanea Plaza, Kingston 6",
      "parish": "Kingston",
      "latitude": 17.9908,
      "longitude": -76.7778,
      "is_active": true
    }
  ],
  "total": 31
}

GET Price Trends

/v1/trends/product/{product_id} · /v1/trends/category/{category}

Price history time series for a specific product or category. Available windows: 30, 60, or 90 days. 2 credits per request.

Query parameters

Parameter	Type	Description
days	30 \| 60 \| 90	Lookback window. Default: 30
store_id	UUID	Limit to a single store

Example — product trend

curl "https://data.buyersmarket.app/v1/trends/product/d7e8f9...?days=30" \
  -H "X-API-Key: bm_your_key"

Response schema

{
  "product_id": "uuid",
  "product_name": "Grace Full Cream Milk 1L",
  "days": 30,
  "min_price": 399.00,
  "max_price": 465.00,
  "avg_price": 425.50,
  "pct_change": -2.4,
  "data_points": [
    { "date": "2026-02-01", "avg_price": 435.00, "observation_count": 7 },
    { "date": "2026-02-02", "avg_price": 432.00, "observation_count": 6 }
  ]
}

GET Market & BGPI

/v1/market/bgpi · /v1/market/summary

The BuyersMarket Grocery Price Index (BGPI) is a composite measure of the cost of a standard basket of Jamaican staples, updated daily. 1 credit per request.

BGPI response schema

{
  "date": "2026-03-03",
  "index_value": 1243.75,
  "basket_size": 50,
  "categories": {
    "Produce": { "avg_price": 285.40, "pct_change_30d": 1.2 },
    "Dairy": { "avg_price": 425.00, "pct_change_30d": -0.8 },
    "Meat": { "avg_price": 890.20, "pct_change_30d": 3.1 }
  },
  "stores_covered": 31,
  "generated_at": "2026-03-03T07:00:00Z"
}

Market summary endpoint

GET /v1/market/summary

{
  "total_products": 18302,
  "total_prices": 20932,
  "total_stores": 31,
  "categories": ["Dairy","Produce","Meat","Beverages",...],
  "last_scraped_at": "2026-03-03T06:30:00Z",
  "data_freshness_hours": 1.5
}

API Keys

Endpoint	Method	Description
/v1/keys/me	GET	Your key details, quota used, tier

GET /v1/keys/me

{
  "key_prefix": "bm_abc123",
  "name": "University of the West Indies",
  "tier": "research",
  "monthly_quota": 1000,
  "quota_used": 142,
  "quota_remaining": 858,
  "is_active": true,
  "created_at": "2026-02-15T10:00:00Z",
  "last_used_at": "2026-03-03T09:14:00Z"
}

A-B-C Price Ratings

Every price observation carries an A, B, or C rating based on the product's 90-day price history. This tells you whether a price is a good deal relative to recent history.

Grab It!

Current price is at or below the lowest price seen in the last 90 days. Exceptional value.

Fair Price

Within 10% of the 90-day low. A normal price — not a steal, not overpriced.

Hold Off

More than 10% above the 90-day low. This product has been cheaper recently.

Note: Rating is null when fewer than 2 price history records exist for the product.

Pagination

All list endpoints use offset-based pagination.

Field	Type	Description
total	int	Total matching records
page	int	Current page number (1-indexed)
page_size	int	Records returned in this response
has_next	bool	Whether more pages exist

Iterate all pages

import httpx

client = httpx.Client(
    base_url="https://data.buyersmarket.app",
    headers={"X-API-Key": "bm_your_key"},
)

offset, all_prices = 0, []
while True:
    resp = client.get("/v1/prices", params={"category": "Dairy", "limit": 200, "offset": offset})
    page = resp.json()
    all_prices.extend(page["data"])
    if not page["has_next"]:
        break
    offset += page["page_size"]

print(f"Fetched {len(all_prices)} dairy prices")

Authentication

Detail	Value
Header name	X-API-Key
Key format	bm_<32 chars>
Error on missing key	HTTP 401
Error on inactive key	HTTP 403
Quota exhausted	HTTP 429