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 Query Builder to effortlessly create complex URLs.

Format & Projections
  • Append ?format=csv to the URL to instantly download the payload as a formatted CSV spreadsheet. Defaults to JSON.
  • Append ?fields=roaster,origin,price-low to restrict the JSON payload to only the fields you need, saving bandwidth.
Query Parameters (Comma separated for OR logic)
  • page (int) - Default: 1
  • limit (int) - Default: 50. Dev Tier max: 1000. Standard Tier max: 200.
  • historical (boolean) - Set to true to include inactive beans (Dev Tier only).
  • origin (string) - e.g., ?origin=Ethiopia,Colombia
  • exclude_process (string) - e.g., ?exclude_process=Decaf
  • price_min / price_max (number) - Apply range filters to numerical data like price, gram, and elevation.
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/terms?list=categoryPublic

Fetch standardized lists of strings used within the database. No API Key required.

Categories: roasters, origins, varieties, processes

3. Access Tiers

Standard Access

  • Data: Available Beans across all Roasters (~5000+)
  • Daily Quota: 20,000 Beans Exported / day
  • Rate Limit: 1 request per 2 seconds
  • Max Call Limit: 200 beans per call

Perfect for coffee enthusiasts and app developers.

Patreon Supporter (Dev Tier)

  • Data: Entire database (Inc. Historical)
  • Daily Quota: 500,000 Beans Exported / day
  • Rate Limit: 5 requests per second
  • Max Call Limit: 1,000 beans per call

Access to higher limits and bulk downloads made for our commercial partners.

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.