API Documentation

This document provides an overview of the OlioWise API endpoints for accessing olive oil data.

Base URL

All API endpoints are available at: https://www.oliowise.com/api/

API Versions

Version 1 (v1)

Returns data in JSON object format with named fields.

Version 2 (v2)

Returns data in optimised array format for better performance and smaller payload sizes.

Available Endpoints

API v1 Endpoints

GET /api/v1/oils.json

Returns a list of all olive oils with detailed information.

Response Format: Array of objects Fields:

• title - Oil name
• url - Relative URL to oil page
• country - Country of origin
• year - Latest recorded release year; not necessarily a producer-disclosed harvest year
• producer_harvest_year - Newest release year with recorded producer-site provenance, or null; may be older than year. Historical disclosure, not current stock or a guarantee of the vintage supplied.
• region - Production region
• phenols - Phenolic content (mg/kg)
• estimated_phenols - Estimated phenolic content
• price_per_litre - Price per litre
• currency - Currency code
• image - Image URL
• overall_score - Overall score (0-100)
• trust_level - Trust level (Low/Medium/High)
• availability - Stock availability
• release_date - Release date
• release_date_confidence - Confidence in release date

GET /api/v1/producers.json

Returns a list of all olive oil producers.

Response Format: Array of objects Fields:

• name - Producer name
• slug - URL slug
• url - Relative URL to producer page
• country - Country of operation
• region - Production region
• state - State/province
• oil_count - Number of oils produced
• varieties - Array of olive varieties used
• latest_year - Most recent harvest year
• overall_score - Producer overall score
• image - Producer image URL
• description - Producer description
• website - Producer website URL

GET /api/v1/regions.json

Returns a list of all production regions.

Response Format: Array of objects Fields:

• name - Region name
• slug - URL slug
• url - Relative URL to region page
• country - Country
• state - State/province
• oil_count - Number of oils from region
• producer_count - Number of producers in region
• varieties - Array of varieties grown in region
• avg_polyphenols - Average polyphenol content

GET /api/v1/varieties.json

Returns a list of all olive varieties.

Response Format: Array of objects Fields:

• name - Variety name
• url - Relative URL to variety page
• oil_count - Number of oils using this variety
• intensity - Flavour intensity (1-10)
• profile - Flavour profile (Mild/Medium/Robust)
• bitterness - Bitterness level
• pungency - Pungency level
• fruitiness - Fruitiness level
• polyphenol_content - Typical polyphenol content
• primary_notes - Array of primary flavour notes

API v2 Endpoints

GET /api/v2/oils.json

Returns olive oil data in optimised array format for better performance.

Response Format: Object with fields and data arrays

• fields - Array of field names
• data - Array of arrays, each containing values in the same order as fields

v2 oils fields include the v1 oil fields plus producer, state, composition, varieties, producer_responsiveness, tags, certifications, ffa (latest-release free fatty acids, %) and harvest_date (ISO date when known).

Example Response Structure:

{
  "fields": ["title", "url", "country", "year", "region", "phenols", ...],
  "data": [
    ["Oil Name 1", "/oils/oil-1/", "Australia", 2024, "Region 1", 250, ...],
    ["Oil Name 2", "/oils/oil-2/", "New Zealand", 2024, "Region 2", 300, ...]
  ]
}

GET /api/v2/oils-by-competition/<competition-key>.json

Returns only the catalogue oils with recorded awards at the named competition, plus their award history at that competition. For example: /api/v2/oils-by-competition/olive-japan.json.

Response format: fields and data describe unique oil rows; awardFields and awards describe award rows in the same compact field-order format. Each award's oil_index refers to its oil's zero-based position in data.

Oil rows describe current catalogue information. Award rows preserve competition year, release year, original award label, medal group and category separately. Current oil prices or availability do not describe the historical winning release.

Filters apply to matching awards, then return distinct oils. An oil with Gold and Silver wins in different years can appear in both medal groups; group totals therefore need not sum to the all-oils total. Year filtering uses competition year. Gold is an exact medal group; higher honours and other recognition remain separate.

The endpoint is a static file: query parameters do not filter its response. Competition pages such as /competitions/olive-japan/?year=2025&tier=gold filter locally after loading that competition's JSON. They load it when a visitor searches, filters, sorts or requests more oils. They do not fetch the full site catalogue or create separate HTML pages for each year and medal. Page requests include a payload version in the URL to invalidate cached data when the underlying catalogue changes.

Usage Examples

Fetching All Oils (v1)

fetch('/api/v1/oils.json')
  .then(response => response.json())
  .then(oils => {
    oils.forEach(oil => {
      console.log(`${oil.title} - ${oil.trust_level} trust`);
    });
  });

Fetching All Oils (v2 - Optimised)

fetch('/api/v2/oils.json')
  .then(response => response.json())
  .then(result => {
    const { fields, data } = result;
    const titleIndex = fields.indexOf('title');
    const trustIndex = fields.indexOf('trust_level');
    
    data.forEach(oil => {
      console.log(`${oil[titleIndex]} - ${oil[trustIndex]} trust`);
    });
  });

Fetching Producers

fetch('/api/v1/producers.json')
  .then(response => response.json())
  .then(producers => {
    producers.forEach(producer => {
      console.log(`${producer.name} - ${producer.oil_count} oils`);
    });
  });

Data Notes

• All endpoints return JSON data
• Dates are in ISO format where applicable
• Phenolic content is measured in mg/kg
• Trust scores range from 0-100
• Currency codes follow ISO 4217 standard
• Images are relative URLs from the site root
• null values indicate missing or unavailable data

Rate Limiting

Currently, no rate limiting is applied to these endpoints. However, please be respectful with your usage.

Support

For questions about the API or to report issues, please contact us.