API Documentation

This document provides an overview of the Extra Virgin Vault API endpoints for accessing olive oil data.

Base URL

All API endpoints are available at: https://www.extravirginvault.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 - Harvest year
• 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
• trust_score - Trust 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
• trust_score - Producer trust 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 (same as v1 oils endpoint)
• data - Array of arrays, each containing values in the same order as fields

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, ...]
  ]
}

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.