# Olea Markets — Olea Price API

> Daily benchmark for olive oil producer prices in the world's leading producing markets
> ("Olea Price"), built exclusively from
> official and semi-official public sources (ministry bulletins, market boards, cooperatives).
> Machine-first REST API with a uniform JSON envelope, an MCP server for AI agents, and a fully
> reproducible methodology: every published value stores its exact inputs (observation ids and
> applied weights) plus the methodology version.

Base URL: https://api.oleamarkets.com
Unit: EUR/kg (3 decimals) for all prices; metric tons for stocks. Publication: daily.
Methodology (v1.0.0, normative): https://oleamarkets.com/methodology
Docs: https://api.oleamarkets.com/docs
OpenAPI 3.1 spec: https://api.oleamarkets.com/openapi.json
MCP endpoint (JSON-RPC 2.0, protocol 2025-03-26): POST https://api.oleamarkets.com/mcp
Contact: hello@oleamarkets.com · Plans & keys: https://oleamarkets.com/pricing

## Indices

- OLEA-EVOO-ES — Extra Virgin Olive Oil, Spain
- OLEA-VIRGIN-ES — Virgin Olive Oil, Spain
- OLEA-LAMP-ES — Lampante Olive Oil, Spain
- OLEA-EVOO-IT — Extra Virgin Olive Oil, Italy
- OLEA-EVOO-EU — Extra Virgin Olive Oil, EU production-weighted composite (ES 62%, IT 15%, EL 13%, PT 10%)

Every value ships a reliability block: sources_count, observations_count, confidence (0-1),
last_updated, methodology_version. Values carried forward on days without fresh observations are
flagged "stale": true.

## Authentication

API key as Bearer token or ?apikey= query parameter. Issue keys at https://oleamarkets.com/pricing.

Plans (monthly or annual — annual = 2 months free; billed in EUR inside Europe and USD elsewhere — same numerals):
starter ($99.99 / €99.99, 10,000 req/month, 60 req/min, widget 1,000 views/day, paid endpoints, 1 year of history, email support) ·
pro ($199.99 / €199.99, 50,000 req/month, 120 req/min, widget 10,000 views/day, paid endpoints, full history, priority support) ·
business ($499.99 / €499.99, 250,000 req/month, 240 req/min, widget 100,000 views/day, paid endpoints, full history, specialized support) — API plan code "enterprise".
Enterprise (custom — contact us): from $10,000 / €10,000 per year — custom rate limits and quotas, redistribution licence, dedicated support & SLA, onboarding. Contact hello@oleamarkets.com.
Every plan starts with a 7-day free trial limited to 100 calls (quota capped at 100 while the trial is active).
All plans include all markets and daily index updates.
Paid endpoints: historical, regional, spread, stocks.

## Endpoints

GET /v1/status — pipeline health + per-source freshness + latest value of each index. NO key needed.
    curl https://api.oleamarkets.com/v1/status

GET /v1/symbols — metadata of the 5 indices (grade, country, unit, frequency, methodology). Key needed.
    curl -H "Authorization: Bearer olea_YOUR_KEY" https://api.oleamarkets.com/v1/symbols

GET /v1/latest?index=OLEA-EVOO-ES — latest value with 1d/1w/1y % changes and stale flag. Omit index for all five. Key needed.
    curl -H "Authorization: Bearer olea_YOUR_KEY" "https://api.oleamarkets.com/v1/latest?index=OLEA-EVOO-ES"

GET /v1/historical?index=OLEA-EVOO-ES&from=2026-01-01&to=2026-07-14 — daily series. PAID plan.
    Starter sees max 1 year back from today (response flags plan_limited: true when clamped).
    curl -H "Authorization: Bearer olea_YOUR_KEY" "https://api.oleamarkets.com/v1/historical?index=OLEA-EVOO-ES&from=2026-01-01&to=2026-07-14"

GET /v1/regional?country=ES&region=jaen&grade=evoo — non-quarantined observations, last 30 days. PAID plan.
    curl -H "Authorization: Bearer olea_YOUR_KEY" "https://api.oleamarkets.com/v1/regional?country=ES&region=jaen&grade=evoo"

GET /v1/spread?a=evoo&b=lampante&country=ES — spread between two grades: absolute (a-b) and % vs b. PAID plan.
    Uses latest index values when available, otherwise 30-day observation means.
    curl -H "Authorization: Bearer olea_YOUR_KEY" "https://api.oleamarkets.com/v1/spread?a=evoo&b=lampante&country=ES"

GET /v1/stocks?country=ES — official market stocks in tons, newest month first. PAID plan.
    curl -H "Authorization: Bearer olea_YOUR_KEY" "https://api.oleamarkets.com/v1/stocks?country=ES"

GET /v1/sources — data sources with tier and freshness (last successful fetch, last observation). Key needed.
    curl -H "Authorization: Bearer olea_YOUR_KEY" https://api.oleamarkets.com/v1/sources

## Response envelope (every response, success and error)

{"success": true, "data": ..., "unit": "EUR/kg", "metric": "price.index.latest",
 "reliability": {"sources_count": 3, "observations_count": 17, "confidence": 0.87,
 "last_updated": "2026-07-14T06:00:12Z", "methodology_version": "1.0.0",
 "methodology_url": "https://oleamarkets.com/methodology"},
 "meta": {"request_id": "uuid", "credits_used": 1}}

Errors use the same envelope with success: false and an error object
{code, message, docs_url}. Codes: unauthenticated (401), payment_required (403),
not_found (404), validation_error (422), quota_exceeded (429), rate_limited (429).

## MCP tools (POST /mcp)

- get_olive_oil_price (index optional) — latest value(s), no auth
- get_price_history (index, from, to) — requires paid key as Authorization: Bearer header
- compare_grades (a, b, country) — grade spread, no auth
- get_market_stocks (country optional) — stocks in tons, no auth
- get_sources_status () — pipeline freshness, no auth

Example:
    curl -X POST https://api.oleamarkets.com/mcp -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'