Skip to main content
The Bhumi REST API gives you programmatic access to a dataset of verified local farms across the United States. You can search by location, filter by products, certifications, and place type, retrieve full farm profiles, and pull platform-level statistics.

​
Base URL

All requests go to: 
https://api.bhumifarms.co
There is no versioning prefix on the base URL. Each endpoint includes its own version segment (e.g., /v1/search).

​
Authentication

Every request must include your API key in the X-API-Key header. 
X-API-Key: bh_live_your_key_here
Never expose your API key in client-side code or public repositories. Use environment variables to manage keys in your application.
If the key is missing or invalid, the API returns 401 Unauthorized. If the key is valid but does not have permission for the requested operation, it returns 403 Forbidden.

​
Response envelope

List endpoints (/v1/farms, /v1/search) wrap results in a consistent envelope: 
{
  "data": [...],
  "meta": {
    "count": 20,
    "total": 142,
    "page": 1,
    "per_page": 20,
    "has_more": true
  },
  "links": {
    "self": "/api/v1/farms?page=1&per_page=20",
    "next": "/api/v1/farms?page=2&per_page=20"
  }
}
​
data
object[]
Array of farm or search result objects.
​
meta
object
​
links
object
Convenience links for the current and next page. links.next is omitted when has_more is false.
Single-resource endpoints (/v1/farms/:id, /v1/stats) use a simpler envelope with no meta or links: 
{
  "data": { ... }
}

​
Rate limit headers

Every response includes rate limit information:
HeaderDescription
X-RateLimit-LimitTotal requests allowed in the current window for your plan.
X-RateLimit-RemainingRequests remaining in the current window.
When X-RateLimit-Remaining reaches 0, subsequent requests return 429 Too Many Requests. Use these headers proactively to pace your request rate and avoid hitting the limit.

​
Available endpoints

MethodPathDescription
GET/v1/searchGeo-radius farm search by latitude and longitude.
GET/v1/foodProduct-first search — find farms that carry a specific product.
GET/v1/farmsList and filter farms by state, products, certifications, and more.
GET/v1/farms/:idRetrieve a single farm’s full profile.
GET/v1/farms/:id/productsProduct listings for a specific farm.
GET/v1/farms/:id/hoursOperating hours for a specific farm (paid tier).
GET/v1/availabilityCheck if a product is in stock at a farm.
GET/v1/statsPlatform-level counts, coverage, and top product data.
GET/v1/market/landscapeRaw market data: farm counts, quality distribution, product/cert/practice breakdowns.
GET/v1/market/pricesCompare pricing for a product across farms in an area.
GET/v1/market/competitorsFind farms with overlapping products near a specific farm.
GET/v1/market/differentiatorsWhat makes a farm unique vs its neighbors.
GET/v1/market/deliveryDelivery and pickup stats for farms near a location.

​
Tier differences

Your API key is scoped to either the free or paid tier. The tier controls which fields are returned on farm objects.

​
Free tier fields

Free tier responses include the core discovery fields: id, name, city, state, lat, lng, place_type, products, categories For search results, distance_mi is also included. Paid tier responses include all free fields plus: address, zip, phone, website, email, description, story, farmer_name, tagline, certifications, practices, delivery_options, images, image_url, farmer_photo_url, google_rating, google_review_count, quality_tier, quality_score, quality_tier_label, verification_status, hours_json, payment_methods, price_range, founded_year In addition, GET /v1/farms/:id on the paid tier includes a nested product_listings array with individual product entries (id, name, price, unit, category, in_stock).
If a field appears as null rather than missing from the response, it means the farm exists in the dataset but that particular attribute has not been collected yet.