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
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, soldout, available

Default tier for testing.

Standard Access

  • Data: All Active Beans (~5000+)
  • Daily Quota: 20,000 Beans / day
  • Rate Limit: 1 request per 1 sec
  • Max Call Limit: 200 beans / call
  • Stripped Fields: image, soldout, available

Requires Patreon "Loffee Supporter" or "Loffee Lover".

Developer Access

  • Data: Entire database (Inc. Historical)
  • Daily Quota: 250,000 Beans / day
  • Rate Limit: 2 requests per second
  • Max Call Limit: 1,000 beans / call
  • Stripped Fields: None (Full Payload)

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

4. Status Codes

200Success. Your query was executed properly.
401Unauthorized. Missing or invalid API Key. Ensure it is passed in the header or via the ?api_key= parameter.
429Too Many Requests. You have either exceeded your daily quota or triggered the burst rate limit. Please add a delay between rapid calls.
500Internal Server Error. An issue occurred processing the query on our end.

5. API Terms of Use

Access to the Bean Base API is granted via a limited, non-exclusive, revocable license. Standard Access is strictly limited to personal, educational, or internal non-commercial projects. Commercial integration, high-volume production use, and bulk data extraction are exclusively permitted for Patreon Supporters (Dev Tier). Regardless of your access tier, you may not mass-scrape, mirror, redistribute, or resell raw API data as a standalone product. 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.