Skip to content

Quickstart

MealCP is a REST API for grocery prices, catalogue, and stock data across European retailers - one endpoint to search 100k+ products, compare retailers, and track price history. The base URL is https://api.mealcp.com.

This quickstart covers the three moves every integration starts with: run a search, read the response, and check your credit balance. You only need a terminal with curl (or any HTTP client) and two minutes.

Grab a key

Section titled “Grab a key”

No signup needed to try it - use the shared free key:

Terminal window
export MEALCP_API_KEY="mcp_live_O-mCAQOybAm5CVm5xuFuCuKbpkMhNig_XVLlNBmWn1o"

The free key is capped at 200 credits/month, 5 requests/min per IP - fine for exploring, tight for building. Building something real? Request a free beta key - 10,000 credits/month, delivered within 24 hours.

Export the key as shown so the examples below can pick it up from $MEALCP_API_KEY. Every request that counts against the cap sends it in the X-API-Key header; keep it server-side in real applications so it can’t be extracted from a browser bundle.

Section titled “Your first search”

What does milk cost across Hungarian retailers right now?

Terminal window
curl -H "X-API-Key: $MEALCP_API_KEY" \
  "https://api.mealcp.com/v1/search?q=tej&country=HU&sort=unit_price_asc&page_size=3"

Four parameters do the work:

  • q=tej - “milk” in Hungarian. Queries match the retailer-language product names, so ask in the language of the country you target.
  • country=HU - scope the search to Hungarian retailers.
  • sort=unit_price_asc - order by normalized price per liter, cheapest first, so 0.5 l and 1 l cartons compare fairly.
  • page_size=3 - trim the page to keep the example short (max 100).
{
  "query": "tej",
  "found": 366,
  "hits": [
    {
      "id": "rp_01a0145398b47b208224e57d6f126eb1",
      "name": "Auchan Kedvenc UHT tej 2,8% 1 l",
      "brand": "Auchan",
      "retailer_slug": "auchan-hu",
      "quantity_value": 1.0,
      "quantity_unit": "l",
      "latest_price": 239.0,
      "latest_unit_price": 239.0,
      "latest_unit_price_uom": "l",
      "currency": "HUF",
      "latest_observed_at": "2026-08-20T05:30:31Z",
      "category_path": ["dairy-eggs", "milk", "milk/plain"],
      "url": "https://auchan.hu/shop/auchan-kedvenc-uht-tej-2-8-1-l.p-550801"
    }
  ],
  "facets": [
    {
      "field": "retailer_slug",
      "counts": [
        { "value": "tesco-hu", "count": 190 },
        { "value": "auchan-hu", "count": 145 },
        { "value": "lidl-hu", "count": 31 }
      ]
    }
  ]
}

One query, three retailers, unit-normalized prices (sort=unit_price_asc compares 1 l cartons against 0.5 l ones fairly). The response above is live

  • prices refresh from nightly retailer runs, so your numbers will differ.

How to read it:

  • found: 366 is the total match count - 366 milk products across Hungarian chains; hits holds the current page only.
  • Each hit carries the fields you’d show a user: name, brand, retailer, pack size, latest price, and the retailer’s product page URL.
  • facets counts matches per filterable value - the basis for building filter chips (re-run the search with &retailer=tesco-hu to apply one).

From here the API stays predictable:

  • Filter by category, brand, tag, city, price bounds - see the full Search reference.
  • Grab any hit’s id for price history - every observation we’ve ever recorded for that product.
  • Swap country=HU for FI, AT, or GR. See what’s covered on the coverage map.

Check your balance

Section titled “Check your balance”

Every request costs credits (a search is 1). Check yours any time:

Terminal window
curl -H "X-API-Key: $MEALCP_API_KEY" "https://api.mealcp.com/v1/me"
{
  "name": "Free key",
  "email": "free@mealcp.com",
  "monthly_credit_cap": 200,
  "credits_remaining": 187,
  "window_resets_at": "2026-09-01T00:00:00Z"
}

The call itself is free. The window is a rolling 30 days from your first request, and window_resets_at tells you exactly when the balance tops back up to your cap - schedule batch jobs around it, or request a beta key for a bigger allowance.

Details in the Me reference and Credits & limits.

If the request fails

Section titled “If the request fails”
  • 401 unauthorized - the key isn’t reaching the API. Check the export landed in the same shell you run curl in (echo $MEALCP_API_KEY) and that the header reads X-API-Key, exactly.
  • 429 with Retry-After - you hit the free key’s 5 requests/min per IP. Wait the number of seconds the header names, then continue.
  • 402 - the credit cap for this window is gone. Check window_resets_at via /v1/me, or request a beta key for 10,000 credits/month.

Everything else - the full error envelope, all status codes - is covered in Credits & limits.

Where next?

Section titled “Where next?”
  • Full endpoint reference: REST API
  • Prefer an AI client? uvx mealcp-mcp gives Claude, Cursor, or opencode live grocery prices - MCP integration
  • Pricing model, rate limits, error codes: Credits & limits