{"openapi":"3.1.0","info":{"title":"Olea Markets API","version":"1.0.0","summary":"Olea Price — daily benchmark for olive oil producer prices in the world's leading producing markets.","description":"Machine-first API for the Olea Price olive oil benchmarks (EUR/kg, daily) plus regional observations, grade spreads and official market stocks. Every JSON response — success and error — uses the same envelope with a reliability block (sources_count, observations_count, confidence, last_updated, methodology_version). Methodology v1.0.0 is normative and every published value is bit-for-bit reproducible from its stored inputs. Agent-native surfaces: https://api.oleamarkets.com/llms.txt, https://api.oleamarkets.com/docs and an MCP server at POST /mcp (JSON-RPC 2.0, not described in this spec). 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 calls/month, 60 req/min, widget 1,000 views/day, 1 year of history, email support) · Pro $199.99 / €199.99 (50,000 calls/month, 120 req/min, widget 10,000 views/day, full history, priority support) · Business $499.99 / €499.99 (250,000 calls/month, 240 req/min, widget 100,000 views/day, full history, specialized support). 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). Keys: https://oleamarkets.com/pricing.","contact":{"name":"Olea Markets API","email":"hello@oleamarkets.com","url":"https://oleamarkets.com"}},"servers":[{"url":"https://api.oleamarkets.com","description":"Production"}],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"tags":[{"name":"indices","description":"Olea Price index values"},{"name":"market","description":"Regional observations, spreads and stocks"},{"name":"meta","description":"Symbols, sources and service health"}],"paths":{"/v1/symbols":{"get":{"tags":["meta"],"operationId":"listSymbols","summary":"The five published indices with rich metadata","description":"Static metadata for every Olea Price index: code, label, quality grade, country (null for the EU composite), unit, decimals, daily frequency and methodology. Available on every plan. metric: meta.symbols.","responses":{"200":{"description":"List of index descriptors wrapped in the success envelope.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Symbol"}}}}]},"examples":{"symbols":{"value":{"success":true,"data":[{"code":"OLEA-EVOO-ES","label":"Olea Price — Extra Virgin Olive Oil, Spain","grade":{"code":"evoo","label":"Extra Virgin Olive Oil"},"country":"ES","scope":"country","unit":"EUR/kg","decimals":3,"frequency":"daily","methodology_version":"1.0.0","methodology_url":"https://oleamarkets.com/methodology"}],"unit":"EUR/kg","metric":"meta.symbols","reliability":{"sources_count":0,"observations_count":0,"confidence":1,"last_updated":"2026-07-14T08:00:00Z","methodology_version":"1.0.0","methodology_url":"https://oleamarkets.com/methodology"},"meta":{"request_id":"3f7f0f1e-8f0a-4a52-9f9b-1c2d3e4f5a6b","credits_used":1}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/latest":{"get":{"tags":["indices"],"operationId":"getLatest","summary":"Latest value of one index, or of all five","description":"Latest published Olea Price value with 1-day, 1-week and 1-year percentage changes (null when no history reaches that far) and the stale flag (value carried forward, no fresh observations in the 14-day window). Omit ?index to receive a list with all five indices. Available on every plan. metric: price.index.latest.","parameters":[{"name":"index","in":"query","required":false,"schema":{"$ref":"#/components/schemas/IndexCode"},"description":"Index code. Omit for all indices (data becomes a list)."}],"responses":{"200":{"description":"Latest value(s) wrapped in the success envelope. Reliability comes from the stored index value.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/LatestValue"},{"type":"array","items":{"$ref":"#/components/schemas/LatestValue"}}]}}}]},"examples":{"single":{"value":{"success":true,"data":{"index":"OLEA-EVOO-ES","date":"2026-07-14","value_eur_kg":4.512,"change_1d":-0.35,"change_1w":1.12,"change_1y":-23.4,"stale":false},"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":"3f7f0f1e-8f0a-4a52-9f9b-1c2d3e4f5a6b","credits_used":1}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/historical":{"get":{"tags":["indices"],"operationId":"getHistorical","summary":"Daily historical series of one index (paid)","description":"Daily series between from and to (inclusive). Requires a paid plan (starter, pro, enterprise); free keys receive 403 payment_required. Starter plans see at most 1 year back from today: the lower bound is clamped and plan_limited is set to true. metric: price.index.historical.","parameters":[{"name":"index","in":"query","required":true,"schema":{"$ref":"#/components/schemas/IndexCode"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Y-m-d. Defaults to one year before to."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Y-m-d. Defaults to today."}],"responses":{"200":{"description":"Series wrapped in the success envelope.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HistoricalSeries"}}}]},"examples":{"series":{"value":{"success":true,"data":{"index":"OLEA-EVOO-ES","from":"2026-07-01","to":"2026-07-14","plan_limited":false,"count":2,"series":[{"date":"2026-07-13","value_eur_kg":4.528,"confidence":0.91,"stale":false},{"date":"2026-07-14","value_eur_kg":4.512,"confidence":0.87,"stale":false}]},"unit":"EUR/kg","metric":"price.index.historical","reliability":{"sources_count":3,"observations_count":34,"confidence":0.87,"last_updated":"2026-07-14T06:00:12Z","methodology_version":"1.0.0","methodology_url":"https://oleamarkets.com/methodology"},"meta":{"request_id":"3f7f0f1e-8f0a-4a52-9f9b-1c2d3e4f5a6b","credits_used":1}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/PaymentRequired"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/regional":{"get":{"tags":["market"],"operationId":"getRegional","summary":"Regional price observations, last 30 days (paid)","description":"Non-quarantined price observations from the last 30 days, newest first, optionally filtered by country (ISO2), region and quality grade. Requires a paid plan. metric: price.observations.regional.","parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2},"example":"ES"},{"name":"region","in":"query","required":false,"schema":{"type":"string"},"example":"jaen"},{"name":"grade","in":"query","required":false,"schema":{"$ref":"#/components/schemas/QualityGrade"}}],"responses":{"200":{"description":"Observations wrapped in the success envelope.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RegionalObservations"}}}]},"examples":{"observations":{"value":{"success":true,"data":{"window_days":30,"count":1,"observations":[{"date":"2026-07-11","source":"ES_JUNTA_ANDALUCIA","quality_grade":"evoo","country":"ES","region":"jaen","market":null,"price_eur_kg":4.45,"volume_tons":320.5}]},"unit":"EUR/kg","metric":"price.observations.regional","reliability":{"sources_count":1,"observations_count":1,"confidence":0.33,"last_updated":"2026-07-11T09:12:44Z","methodology_version":"1.0.0","methodology_url":"https://oleamarkets.com/methodology"},"meta":{"request_id":"3f7f0f1e-8f0a-4a52-9f9b-1c2d3e4f5a6b","credits_used":1}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/PaymentRequired"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/spread":{"get":{"tags":["market"],"operationId":"getSpread","summary":"Spread between two quality grades (paid)","description":"Latest values of two grades in one country plus absolute spread (a - b) and percentage spread relative to b. Each leg uses the latest index value when an Olea Price index covers the (grade, country) pair (basis \"index\"), otherwise the plain mean of publishable observations from the last 30 days (basis \"observations\"). Requires a paid plan. metric: price.spread.","parameters":[{"name":"a","in":"query","required":true,"schema":{"$ref":"#/components/schemas/QualityGrade"},"description":"First grade (minuend)."},{"name":"b","in":"query","required":true,"schema":{"$ref":"#/components/schemas/QualityGrade"},"description":"Second grade (base of the % spread)."},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"ES"}}],"responses":{"200":{"description":"Spread wrapped in the success envelope.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Spread"}}}]},"examples":{"spread":{"value":{"success":true,"data":{"country":"ES","a":{"grade":"evoo","basis":"index","index":"OLEA-EVOO-ES","date":"2026-07-14","value_eur_kg":4.512},"b":{"grade":"lampante","basis":"index","index":"OLEA-LAMP-ES","date":"2026-07-14","value_eur_kg":3.401},"spread_abs_eur_kg":1.111,"spread_pct":32.67},"unit":"EUR/kg","metric":"price.spread","reliability":{"sources_count":5,"observations_count":25,"confidence":0.74,"last_updated":"2026-07-14T06:00:12Z","methodology_version":"1.0.0","methodology_url":"https://oleamarkets.com/methodology"},"meta":{"request_id":"3f7f0f1e-8f0a-4a52-9f9b-1c2d3e4f5a6b","credits_used":1}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/stocks":{"get":{"tags":["market"],"operationId":"getStocks","summary":"Official market stocks in tons (paid)","description":"stocks_data rows ordered by month descending, optionally filtered by country. unit: tons, metric: market.stocks. Requires a paid plan.","parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2},"example":"ES"}],"responses":{"200":{"description":"Stock rows wrapped in the success envelope (unit is tons).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Stocks"},"unit":{"type":"string","const":"tons"}}}]},"examples":{"stocks":{"value":{"success":true,"data":{"count":1,"rows":[{"country":"ES","campaign":"2025-26","month":"2026-06-01","stock_tons":512340.5,"outflow_tons":98450,"production_tons":1401200,"source":"ES_AICA"}]},"unit":"tons","metric":"market.stocks","reliability":{"sources_count":1,"observations_count":1,"confidence":1,"last_updated":"2026-07-05T10:00:00Z","methodology_version":"1.0.0","methodology_url":"https://oleamarkets.com/methodology"},"meta":{"request_id":"3f7f0f1e-8f0a-4a52-9f9b-1c2d3e4f5a6b","credits_used":1}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/PaymentRequired"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sources":{"get":{"tags":["meta"],"operationId":"listSources","summary":"Data sources with tier and freshness","description":"Every configured source with its tier (official, semi_official, cooperative, press), country, active flag and freshness: timestamp of the last successful raw fetch and date of the last observation. Available on every plan. metric: meta.sources.","responses":{"200":{"description":"Sources wrapped in the success envelope.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SourceInfo"}},"unit":{"type":"string","const":"none"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/status":{"get":{"tags":["meta"],"operationId":"getStatus","summary":"Service health and data freshness (no API key)","security":[],"description":"Public health endpoint, no API key required: overall status, per-source freshness and the latest value, date, confidence and stale flag of each index. metric: meta.status, credits_used: 0.","responses":{"200":{"description":"Health snapshot wrapped in the success envelope.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Status"},"unit":{"type":"string","const":"none"}}}]}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key as Bearer token: Authorization: Bearer olea_YOUR_KEY"},"apiKeyQuery":{"type":"apiKey","in":"query","name":"apikey","description":"API key as query parameter: ?apikey=olea_YOUR_KEY"}},"responses":{"Unauthenticated":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unauthenticated":{"value":{"success":false,"data":null,"unit":null,"metric":null,"reliability":null,"error":{"code":"unauthenticated","message":"Missing or invalid API key. Pass it as a Bearer token or ?apikey=.","docs_url":"https://oleamarkets.com/docs"},"meta":{"request_id":"3f7f0f1e-8f0a-4a52-9f9b-1c2d3e4f5a6b","credits_used":0}}}}}}},"PaymentRequired":{"description":"The key's plan does not include this endpoint (free plan).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"payment_required":{"value":{"success":false,"data":null,"unit":null,"metric":null,"reliability":null,"error":{"code":"payment_required","message":"This endpoint requires a paid plan (starter, pro or enterprise). See https://oleamarkets.com/pricing to upgrade.","docs_url":"https://oleamarkets.com/docs"},"meta":{"request_id":"3f7f0f1e-8f0a-4a52-9f9b-1c2d3e4f5a6b","credits_used":0}}}}}}},"NotFound":{"description":"No data matches the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationError":{"description":"Invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"TooManyRequests":{"description":"Monthly quota exhausted (quota_exceeded — during an active 7-day free trial the effective quota is capped at 100 calls and the message says so) or per-minute rate limit hit (rate_limited).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"schemas":{"IndexCode":{"type":"string","enum":["OLEA-EVOO-ES","OLEA-VIRGIN-ES","OLEA-LAMP-ES","OLEA-EVOO-IT","OLEA-EVOO-EU"]},"QualityGrade":{"type":"string","enum":["evoo","virgin","lampante","refined","pomace"]},"Reliability":{"type":"object","description":"How much the returned number can be trusted and which methodology produced it.","properties":{"sources_count":{"type":"integer"},"observations_count":{"type":"integer"},"confidence":{"type":"number","minimum":0,"maximum":1},"last_updated":{"type":["string","null"],"format":"date-time"},"methodology_version":{"type":"string"},"methodology_url":{"type":"string","format":"uri"}},"required":["sources_count","observations_count","confidence","last_updated","methodology_version","methodology_url"]},"Meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"credits_used":{"type":"integer"}},"required":["request_id","credits_used"]},"SuccessEnvelope":{"type":"object","description":"Uniform envelope of every successful response.","properties":{"success":{"type":"boolean","const":true},"data":[],"unit":{"type":"string","description":"EUR/kg for prices, tons for stocks, none for meta endpoints."},"metric":{"type":"string","description":"Semantic metric id, e.g. price.index.latest."},"reliability":{"$ref":"#/components/schemas/Reliability"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["success","data","unit","metric","reliability","meta"]},"ErrorEnvelope":{"type":"object","description":"Uniform envelope of every error response.","properties":{"success":{"type":"boolean","const":false},"data":{"type":"null"},"unit":{"type":"null"},"metric":{"type":"null"},"reliability":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthenticated","payment_required","not_found","validation_error","quota_exceeded","rate_limited","http_500"]},"message":{"type":"string"},"docs_url":{"type":"string","format":"uri"}},"required":["code","message","docs_url"]},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["success","data","unit","metric","reliability","error","meta"]},"Symbol":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/IndexCode"},"label":{"type":"string"},"grade":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/QualityGrade"},"label":{"type":"string"}},"required":["code","label"]},"country":{"type":["string","null"],"description":"ISO2, null for the EU composite."},"scope":{"type":"string","enum":["country","eu_composite"]},"unit":{"type":"string","const":"EUR/kg"},"decimals":{"type":"integer","const":3},"frequency":{"type":"string","const":"daily"},"methodology_version":{"type":"string"},"methodology_url":{"type":"string","format":"uri"}},"required":["code","label","grade","country","scope","unit","decimals","frequency","methodology_version","methodology_url"]},"LatestValue":{"type":"object","properties":{"index":{"$ref":"#/components/schemas/IndexCode"},"date":{"type":"string","format":"date"},"value_eur_kg":{"type":"number"},"change_1d":{"type":["number","null"],"description":"% change vs ~1 day earlier; null without history."},"change_1w":{"type":["number","null"],"description":"% change vs ~1 week earlier; null without history."},"change_1y":{"type":["number","null"],"description":"% change vs ~1 year earlier; null without history."},"stale":{"type":"boolean","description":"True when the value was carried forward with no fresh observations."}},"required":["index","date","value_eur_kg","change_1d","change_1w","change_1y","stale"]},"HistoricalSeries":{"type":"object","properties":{"index":{"$ref":"#/components/schemas/IndexCode"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"plan_limited":{"type":"boolean","description":"True when the range was clamped by the plan's history limit."},"count":{"type":"integer"},"series":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"value_eur_kg":{"type":"number"},"confidence":{"type":"number"},"stale":{"type":"boolean"}},"required":["date","value_eur_kg","confidence","stale"]}}},"required":["index","from","to","plan_limited","count","series"]},"RegionalObservations":{"type":"object","properties":{"window_days":{"type":"integer","const":30},"count":{"type":"integer"},"observations":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"source":{"type":["string","null"]},"quality_grade":{"$ref":"#/components/schemas/QualityGrade"},"country":{"type":"string"},"region":{"type":["string","null"]},"market":{"type":["string","null"]},"price_eur_kg":{"type":"number"},"volume_tons":{"type":["number","null"]}},"required":["date","source","quality_grade","country","region","market","price_eur_kg","volume_tons"]}}},"required":["window_days","count","observations"]},"SpreadLeg":{"type":"object","properties":{"grade":{"$ref":"#/components/schemas/QualityGrade"},"basis":{"type":"string","enum":["index","observations"]},"index":{"type":["string","null"],"description":"Index code when basis is index, null otherwise."},"date":{"type":["string","null"],"format":"date"},"value_eur_kg":{"type":"number"}},"required":["grade","basis","index","date","value_eur_kg"]},"Spread":{"type":"object","properties":{"country":{"type":"string"},"a":{"$ref":"#/components/schemas/SpreadLeg"},"b":{"$ref":"#/components/schemas/SpreadLeg"},"spread_abs_eur_kg":{"type":"number","description":"a minus b, EUR/kg."},"spread_pct":{"type":["number","null"],"description":"Spread as % of leg b."}},"required":["country","a","b","spread_abs_eur_kg","spread_pct"]},"Stocks":{"type":"object","properties":{"count":{"type":"integer"},"rows":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"campaign":{"type":"string"},"month":{"type":"string","format":"date"},"stock_tons":{"type":"number"},"outflow_tons":{"type":["number","null"]},"production_tons":{"type":["number","null"]},"source":{"type":["string","null"]}},"required":["country","campaign","month","stock_tons","outflow_tons","production_tons","source"]}}},"required":["count","rows"]},"SourceInfo":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"tier":{"type":"string","enum":["official","semi_official","cooperative","press"]},"country":{"type":"string"},"active":{"type":"boolean"},"freshness":{"type":"object","properties":{"last_successful_fetch":{"type":["string","null"],"format":"date-time"},"last_observation_date":{"type":["string","null"],"format":"date"}},"required":["last_successful_fetch","last_observation_date"]}},"required":["code","name","tier","country","active","freshness"]},"Status":{"type":"object","properties":{"status":{"type":"string","const":"ok"},"time":{"type":"string","format":"date-time"},"indices":{"type":"array","items":{"type":"object","properties":{"index":{"$ref":"#/components/schemas/IndexCode"},"date":{"type":["string","null"],"format":"date"},"value_eur_kg":{"type":["number","null"]},"stale":{"type":["boolean","null"]},"confidence":{"type":["number","null"]}},"required":["index","date","value_eur_kg","stale","confidence"]}},"sources":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"active":{"type":"boolean"},"last_successful_fetch":{"type":["string","null"],"format":"date-time"},"last_observation_date":{"type":["string","null"],"format":"date"}},"required":["code","active","last_successful_fetch","last_observation_date"]}}},"required":["status","time","indices","sources"]}}}}