Skip to main content
The farms endpoints let you browse the full farm dataset with filtering and sorting, or look up a specific farm by its ID.

​
List farms

GET https://api.bhumifarms.co/v1/farms
Returns a paginated list of farms. On page 1, the response includes a meta.total count of all matching records. Subsequent pages omit meta.total to avoid the overhead of a repeated full count query.

​
Parameters

​
state
string
Filter by US state. Case-insensitive. Accepts both full names and abbreviations (e.g., TX or Texas).
​
place_type
string
Filter by place type. Common values: farm, ranch, market, csa. Must be an exact match.
​
products
string
Comma-separated product names. Returns farms carrying at least one of the listed products. Example: raw milk,pastured pork.
​
categories
string
Comma-separated category names. Returns farms with at least one matching category. Example: dairy,eggs.
​
certifications
string
Comma-separated certification names. Returns farms holding at least one of the listed certifications. Example: USDA Organic.
​
q
string
Free-text search matched against farm name, city, and state. Maximum 120 characters.
​
sort
string
default:"quality"
Sort order for results. Accepted values:
  • quality — Sort by quality score descending (default).
  • name — Sort alphabetically by farm name ascending.
  • rating — Sort by Google rating descending; farms without a rating appear last.
​
page
number
default:"1"
Page number. Minimum 1.
​
per_page
number
default:"20"
Results per page. Minimum 1, maximum 100.

​
Example request

curl "https://api.bhumifarms.co/v1/farms?state=TX&products=raw%20milk&sort=quality&per_page=10" \
  -H "X-API-Key: bh_live_your_key_here"

​
Example response

{
  "data": [
    {
      "id": "farm_xyz789",
      "name": "Lone Star Creamery",
      "city": "Waco",
      "state": "TX",
      "lat": 31.549,
      "lng": -97.147,
      "place_type": "farm",
      "products": ["raw milk", "aged cheddar", "butter"],
      "categories": ["dairy"]
    }
  ],
  "meta": {
    "count": 10,
    "total": 47,
    "page": 1,
    "per_page": 10,
    "has_more": true
  },
  "links": {
    "self": "/api/v1/farms?page=1&per_page=10",
    "next": "/api/v1/farms?page=2&per_page=10"
  }
}
meta.total is only populated on page 1 requests. On page 2 and beyond, it is returned as null.

​
Get a farm by ID

GET https://api.bhumifarms.co/v1/farms/:id
Returns the full profile for a single farm. On the paid tier, the response includes a nested product_listings array.

​
Path parameters

​
id
string
required
The farm’s unique identifier. Must be at least 10 characters. Example: farm_abc123.

​
Example request

curl "https://api.bhumifarms.co/v1/farms/farm_abc123" \
  -H "X-API-Key: bh_live_your_key_here"

​
Example response (free tier)

{
  "data": {
    "id": "farm_abc123",
    "name": "Prairie Farmstead",
    "city": "Sherman",
    "state": "TX",
    "lat": 33.635,
    "lng": -96.609,
    "place_type": "farm",
    "products": ["grass-fed beef", "pastured eggs", "bacon"],
    "categories": ["meat", "eggs"]
  }
}

​
Example response (paid tier)

{
  "data": {
    "id": "farm_abc123",
    "name": "Prairie Farmstead",
    "city": "Sherman",
    "state": "TX",
    "lat": 33.635,
    "lng": -96.609,
    "place_type": "farm",
    "products": ["grass-fed beef", "pastured eggs", "bacon"],
    "categories": ["meat", "eggs"],
    "address": "1420 County Road 412, Sherman, TX 75090",
    "zip": "75090",
    "phone": "+19405551234",
    "website": "https://prairiefarmstead.com",
    "email": "hello@prairiefarmstead.com",
    "description": "Family-run regenerative farm raising cattle and laying hens on native pasture.",
    "farmer_name": "Sarah and Tom Holt",
    "certifications": ["USDA Organic", "Animal Welfare Approved"],
    "practices": ["rotational grazing", "no-till", "composting"],
    "delivery_options": ["on-farm pickup", "local delivery"],
    "quality_score": 87,
    "quality_tier": "high",
    "quality_tier_label": "High Quality",
    "google_rating": 4.8,
    "google_review_count": 42,
    "image_url": "https://cdn.bhumifarms.co/farms/farm_abc123/hero.jpg",
    "hours_json": {
      "saturday": "9:00 AM – 1:00 PM",
      "sunday": "closed"
    },
    "payment_methods": ["cash", "venmo", "credit card"],
    "founded_year": 2014,
    "product_listings": [
      {
        "id": "prod_001",
        "name": "Grass-Fed Ground Beef",
        "price": 9.5,
        "unit": "lb",
        "category": "meat",
        "in_stock": true
      },
      {
        "id": "prod_002",
        "name": "Pastured Eggs",
        "price": 7.0,
        "unit": "dozen",
        "category": "eggs",
        "in_stock": true
      }
    ]
  }
}

​
Response fields

​
id
string
Unique farm identifier.
​
name
string
Farm display name.
​
city
string
City where the farm is located.
​
state
string
Two-letter US state abbreviation.
​
lat
number
Farm latitude.
​
lng
number
Farm longitude.
​
place_type
string
Operation classification: farm, ranch, market, csa, or similar.
​
products
string[]
Array of product names offered by the farm.
​
categories
string[]
Array of product category names.
​
quality_score
number
Numeric quality score from 0–100. Paid tier only.
​
certifications
string[]
Array of certification names. Paid tier only.
​
practices
string[]
Array of farming practice labels (e.g., rotational grazing, no-till). Paid tier only.
​
delivery_options
string[]
Available delivery or pickup modes (e.g., on-farm pickup, local delivery, CSA share). Paid tier only.
​
hours_json
object
Operating hours keyed by day of week. Paid tier only.
​
product_listings
object[]
Nested list of individual product listings. Paid tier only, single-farm endpoint only.