API Documentation

Access real-time Nigerian price data through our RESTful API. Perfect for fintech apps, research platforms, and supply chain analytics.

Overview

The HowMuch API provides programmatic access to real-time grocery and commodity prices across Nigeria. All endpoints return JSON and use standard HTTP methods.

Base URL: https://api.howmuch.ng/api/v1

Available Endpoints:

GET /products/ — List all products
GET /products/{slug}/ — Get product details
GET /products/{slug}/prices/ — Get current prices
GET /search/?q= — Search products & prices
GET /prices/history/ — Historical price data

Authentication

All API requests require an API key. Include your key in the X-API-Key header.

curl -H "X-API-Key: hm_live_your_api_key_here" \
  https://api.howmuch.ng/api/v1/products/

Getting an API key: Once your organization has an account, log in to the API Console to generate and manage your keys. To get started, contact our sales team at sales@howmuch.ng.

Rate Limits

Each API key has a daily request limit based on your plan. Rate limit headers are included in every response.

Plan	Daily Limit	Rate Limit Headers
Basic	10,000/day	Included
Pro	50,000/day	Included
Enterprise	Custom	Included

# Response headers
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847

Error Handling

Standard HTTP status codes are used. Errors return JSON with a detail field.

Code	Meaning
`200`	Success
`401`	Invalid or missing API key
`404`	Resource not found
`429`	Rate limit exceeded

{
  "detail": "Invalid API key."
}

Pagination

List endpoints return paginated results. Default page size is 20, max is 100.

GET /api/v1/products/?page=2&page_size=50

{
  "count": 245,
  "next": "https://api.howmuch.ng/api/v1/products/?page=3&page_size=50",
  "previous": "https://api.howmuch.ng/api/v1/products/?page=1&page_size=50",
  "results": [...]
}

GET

/products/

List all approved products in the catalog.

Query Parameters

search — Filter by product name or category

category — Filter by category slug

page — Page number

page_size — Results per page (max 100)

curl -H "X-API-Key: hm_live_your_key" \
  "https://api.howmuch.ng/api/v1/products/?category=grains"

# Response
{
  "count": 24,
  "results": [
    {
      "slug": "rice",
      "name": "Rice",
      "category": "Grains",
      "image": "https://res.cloudinary.com/...",
      "available_sizes": [
        {"id": 1, "label": "5kg"},
        {"id": 2, "label": "10kg"},
        {"id": 3, "label": "25kg"},
        {"id": 4, "label": "50kg"}
      ]
    }
  ]
}

GET

/products/{slug}/

Get detailed information about a specific product.

curl -H "X-API-Key: hm_live_your_key" \
  "https://api.howmuch.ng/api/v1/products/rice/"

# Response
{
  "slug": "rice",
  "name": "Rice",
  "sku": "HM-A1B2C3D4",
  "description": "Locally grown and imported rice varieties",
  "category": "Grains",
  "image": "https://res.cloudinary.com/...",
  "available_sizes": [
    {"id": 1, "label": "5kg"},
    {"id": 2, "label": "10kg"},
    {"id": 3, "label": "25kg"},
    {"id": 4, "label": "50kg"}
  ]
}

GET

/products/{slug}/prices/

Get current prices for a product from all vendors. Results sorted by price (lowest first). Supports location-based filtering to find vendors near you.

Query Parameters

size — Filter by size label (e.g. "5kg")

brand — Filter by brand name

city — Filter by vendor city (e.g. "Lagos", "Ibadan", "Abuja")

latitude — Your latitude (for distance filtering)

longitude — Your longitude (for distance filtering)

max_distance — Maximum distance in km from lat/lon

Location filtering: Pass latitude, longitude, and max_distance together to get only vendors within that radius. The response includes a distance_km field when coordinates are provided. Alternatively, use city to filter by city name (case-insensitive partial match).

# Basic: get all prices for rice 5kg
curl -H "X-API-Key: hm_live_your_key" \
  "https://api.howmuch.ng/api/v1/products/rice/prices/?size=5kg"

# With location: vendors within 10km of Ikeja, Lagos
curl -H "X-API-Key: hm_live_your_key" \
  "https://api.howmuch.ng/api/v1/products/rice/prices/?size=5kg&latitude=6.6018&longitude=3.3515&max_distance=10"

# By city name
curl -H "X-API-Key: hm_live_your_key" \
  "https://api.howmuch.ng/api/v1/products/rice/prices/?city=ibadan"

# Response
{
  "count": 12,
  "results": [
    {
      "id": 45,
      "product": "Rice",
      "product_slug": "rice",
      "size": "5kg",
      "brand": "Mama Gold",
      "price": "4500.00",
      "vendor_location": {
        "city": "Lagos",
        "state": "Lagos",
        "latitude": 6.6018,
        "longitude": 3.3515
      },
      "distance_km": 2.4,
      "is_available": true,
      "updated_at": "2026-03-14T10:30:00Z"
    }
  ]
}

GET

/search/

Search across products, brands, and categories. Returns matching price listings. Supports location-based filtering just like the prices endpoint.

Query Parameters

q — Search query (required)

city — Filter by vendor city

latitude — Your latitude

longitude — Your longitude

max_distance — Maximum distance in km

# Search for tomato in Lagos
curl -H "X-API-Key: hm_live_your_key" \
  "https://api.howmuch.ng/api/v1/search/?q=tomato&city=lagos"

# Search with geo-radius (5km around Ibadan)
curl -H "X-API-Key: hm_live_your_key" \
  "https://api.howmuch.ng/api/v1/search/?q=rice&latitude=7.3775&longitude=3.9470&max_distance=5"

# Response
{
  "count": 8,
  "results": [
    {
      "id": 78,
      "product": "Tomato Paste",
      "product_slug": "tomato-paste",
      "size": "70g",
      "brand": "Gino",
      "price": "500.00",
      "vendor_location": {
        "city": "Lagos",
        "state": "Lagos",
        "latitude": 6.5244,
        "longitude": 3.3792
      },
      "distance_km": 3.1,
      "is_available": true,
      "updated_at": "2026-03-14T08:15:00Z"
    }
  ]
}

GET

/prices/history/

Get historical price data. Useful for trend analysis, charts, and ML training.

Query Parameters

product — Filter by product slug

days — Number of days to look back (default 30, max 365)

curl -H "X-API-Key: hm_live_your_key" \
  "https://api.howmuch.ng/api/v1/prices/history/?product=rice&days=30"

# Response
{
  "count": 156,
  "results": [
    {
      "product": "Rice",
      "product_slug": "rice",
      "size": "5kg",
      "brand": "Mama Gold",
      "price": "4200.00",
      "recorded_at": "2026-03-10T14:22:00Z"
    }
  ]
}

Location Filtering

The prices and search endpoints support two types of location filtering, which can be combined for precise results.

1. Filter by City

Use the city parameter to filter vendors by their city. This is a case-insensitive partial match, so "lagos", "Lagos", and "LAGOS" all work. You can also use partial names like "iba" for Ibadan.

# Vendors in Ibadan
GET /api/v1/products/rice/prices/?city=ibadan

# Vendors in Lagos
GET /api/v1/search/?q=garri&city=lagos

2. Geo-Radius Filter

Pass latitude, longitude, and max_distance (in km) to find vendors within a radius. The response includes distance_km showing how far each vendor is from your coordinates.

# Vendors within 15km of University of Ibadan
GET /api/v1/products/rice/prices/?latitude=7.3775&longitude=3.9470&max_distance=15

# Response includes distance
{
  "results": [{
    "price": "4500.00",
    "vendor_location": {
      "city": "Ibadan",
      "state": "Oyo",
      "latitude": 7.3965,
      "longitude": 3.9167
    },
    "distance_km": 4.2
  }]
}

3. Combined Filters

You can combine city and geo-radius for more specific results.

# Lagos vendors within 5km of Victoria Island
GET /api/v1/search/?q=bread&city=lagos&latitude=6.4281&longitude=3.4219&max_distance=5

Note: If latitude/longitude are provided without max_distance, the distance_km field will still be calculated in the response, but no distance filtering is applied. Only vendors with registered coordinates participate in geo-filtering.

Code Examples

Python

import requests

API_KEY = "hm_live_your_key"
BASE_URL = "https://api.howmuch.ng/api/v1"

headers = {"X-API-Key": API_KEY}

# Get rice prices
response = requests.get(f"{BASE_URL}/products/rice/prices/", headers=headers)
prices = response.json()

for item in prices["results"]:
    print(f"{item['brand']} {item['size']}: ₦{item['price']} ({item['vendor_location']['city']})")

JavaScript / Node.js

const API_KEY = "hm_live_your_key";
const BASE_URL = "https://api.howmuch.ng/api/v1";

const response = await fetch(`${BASE_URL}/products/rice/prices/`, {
  headers: { "X-API-Key": API_KEY }
});

const { results } = await response.json();
results.forEach(item => {
  console.log(`${item.brand} ${item.size}: ₦${item.price}`);
});

cURL

# List all products
curl -H "X-API-Key: hm_live_your_key" \
  "https://api.howmuch.ng/api/v1/products/"

# Search for tomato prices
curl -H "X-API-Key: hm_live_your_key" \
  "https://api.howmuch.ng/api/v1/search/?q=tomato"

# Get 90-day price history for rice
curl -H "X-API-Key: hm_live_your_key" \
  "https://api.howmuch.ng/api/v1/prices/history/?product=rice&days=90"

Need Help?

Contact our team for integration support, custom plans, or partnership inquiries.

Contact Sales Developer Support