API Documentation

Version 2.0 • Base URL: https://api.loffeelabs.com/api/v2

1. Authentication

All search endpoints require an API key. For production applications, pass your API key securely via the Authorization header.

Authorization: Bearer YOUR_API_KEY

Browser Testing: For quick testing in your browser or Postman, you can pass the key directly in the URL using the ?api_key= parameter.
Example: https://api.loffeelabs.com/api/v2/beans?api_key=your_key_here

2. Endpoints & Querying

GET/beans

Searches and returns a paginated list of coffee beans. Use the interactive Query Builder to effortlessly create complex URLs.

Format & Projections
  • Append ?format=csv to instantly download the payload as a formatted CSV spreadsheet. Defaults to JSON.
  • Append ?fields= with a comma-separated list of keys to restrict the JSON payload to only the fields you need, saving bandwidth.
Export Fields Map
iddateroasterroast-namelinkimagetypedegreeoriginregionproducermin-elevmax-elevvarietyprocessdescriptiontastingharvestprice-lowgram-lowprice-highgram-hightasting-taggeneral-tagroaster-regionroaster-countrysoldoutavailable
Query Parameters
page(int) - Default: 1
limit(int) - Default: 50. Max: 200 (Standard) / 1000 (Dev).
historical(boolean) - Include inactive/archived beans (Dev Tier).
search(string) - Full text search across all records.
String Filters

Accepts comma-separated values for OR logic. Prepend exclude_ to any string parameter below for NOT logic (e.g., ?exclude_process=Decaf).

idroaster-regionroaster-countryroasterroast-typeroast-degreeoriginregionproducervarietyprocesstasting-profiletastinggeneral-tag
Range Filters

Append _min or _max to apply boundaries to numerical or date data (e.g., ?price_min=15&price_max=25).

dateelevationpricegramprice-cupbulk-pricebulk-grambulk-price-cup
GET/beans/syncDev Tier

A highly optimized Delta endpoint that returns only the rows that have been added, modified, or permanently deleted since the date you specify. Perfect for keeping your local database archived and in perfect sync without wasting API quota on full payloads.

?since=Required. Accepts an ISO 8601 date string (e.g., 2026-08-01).
Response Structure
{
  "meta": { "since": "2026-08-01T00:00:00.000Z", "upsertedCount": 2, "deletedCount": 1 },
  "upserted": [ 101, 104 ],
  "deleted": [ 85 ]
}
Pre-defined Categories
typeFilter, Espresso, Omni
degreeUltra Light, Nordic Light, Light, Medium-Light, Medium, Medium-Dark, Dark
roaster-regionNorth America, Europe, Asia-Pacific, Middle East, Africa, South America
general-tagAirworks, Bean Archive, MCL, Roaster Blend, Single Origin, Single Varietal, Traceable, COE
tasting-tagSweet, Caramel, Chocolate, Creamy, Nutty, Roasty, Earthy, Cereal, Vegetal, Spiced, Herbal, Tea Like, Floral, Berries, Common Fruit, Dried Fruit, Stone Fruit, Tropical Fruit, Citrus Fruit, Acidic, Fermented, Complex, Balanced, Clean, Umami
GET
/roasters|/origins|/varieties|/processes
Public

Unauthenticated endpoints returning standardized data from our database. /roasters defaults to returning an array of rich data objects, but you can append ?flat=true to return a simple flat array of strings like the others. No API Key required.

3. Access Tiers

Free Access

  • Data: Latest 1,000 Beans
  • Daily Quota: 2,000 Beans / day
  • Rate Limit: 1 request per 3 sec
  • Max Call Limit: 50 beans / call
  • Stripped Fields: image, tasting-tag, general-tag, description, soldout, available

Default tier for testing.

Developer Access

  • Data: Latest 25,000 Beans (Includes all Active Beans)
  • Daily Quota: 50,000 Beans / day
  • Rate Limit: 2 requests per second
  • Max Call Limit: 1,000 beans / call
  • Stripped Fields: None (Full Payload)

Requires Patreon "Loffee Developer". Access to /bulk.

Commercial Access

Need the complete historical payload (all beans since 2023), 250,000 daily quota limits, and unrestricted access for your enterprise application? Reach out directly to discuss a Commercial Access agreement.

4. API Terms of Use

Access to the Bean Base API is granted via a limited, non-exclusive, revocable license. Free and Developer Access tiers are intended for personal, educational, indie, and internal non-commercial projects. Enterprise integration, high-volume commercial production use, and full historical data extraction are exclusively permitted under a negotiated Commercial Access agreement. Regardless of your access tier, you may not mass-scrape, mirror, redistribute, or resell raw API data as a standalone product or database. You are responsible for keeping your API key confidential and respecting all assigned rate limits. Attribution to LoffeeLabs is required when publishing work directly derived from our datasets.

The Bean Base API and all associated data are provided entirely "as is" and "as available" without warranties of any kind. LoffeeLabs does not guarantee the continuous availability, accuracy, or completeness of the data. To the fullest extent permitted by law, LoffeeLabs shall not be liable for any direct, indirect, incidental, or consequential damages—including loss of profits, data, or business opportunities—arising from your use of or inability to use the API. We reserve the right to monitor usage, modify endpoints, adjust rate limits, or revoke API access at any time, without prior notice, to ensure the stability and security of our platform.

By generating an API key, issuing requests to the Bean Base API, or utilizing the data provided, you acknowledge that you have read, understood, and agree to be bound by these Terms of Use.