Skip to main content
This guide walks you through getting an API key, making your first request, and understanding the response shape.

​
Prerequisites

  • A Bhumi API key. If you don’t have one yet, see Authentication.
  • Any HTTP client (curl, a browser fetch, requests for Python, etc.)

​
Step-by-step

1

Get your API key

Sign up at console.bhumifarms.co to create a free key. Your key will look like:
bh_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
Store it in an environment variable rather than hardcoding it in your source:
export BHUMI_API_KEY="bh_live_your_key_here"
2

Make your first search request

The /v1/search endpoint finds farms near a geographic coordinate. Pass lat, lng, and radius (in miles), and include your key in the X-API-Key header.
curl "https://api.bhumifarms.co/v1/search?lat=33.08&lng=-96.54&radius=25" \
  -H "X-API-Key: $BHUMI_API_KEY"
3

Filter by product

Add a products query parameter (comma-separated) to narrow results to farms that carry specific items:
curl "https://api.bhumifarms.co/v1/search?lat=33.08&lng=-96.54&radius=25&products=grass-fed%20beef,pastured%20eggs" \
  -H "X-API-Key: $BHUMI_API_KEY"
4

Read the response

All search endpoints return the same envelope shape: a data array of farm objects and a meta pagination object.
{
  "data": [
    {
      "id": "farm_abc123",
      "name": "Prairie Farmstead",
      "city": "Sherman",
      "state": "TX",
      "lat": 33.635,
      "lng": -96.609,
      "products": [
        "grass-fed beef",
        "pasture-raised chicken",
        "pastured eggs"
      ],
      "certifications": ["USDA Organic"],
      "quality_score": 87,
      "place_type": "farm",
      "distance_mi": 12.4,
      "delivery_options": [
        "on-farm pickup",
        "local delivery"
      ],
      "website": "https://prairiefarmstead.com"
    }
  ],
  "meta": {
    "count": 20,
    "page": 1,
    "per_page": 20,
    "has_more": true
  }
}
Key fields in each farm object:
FieldTypeDescription
idstringUnique farm identifier
namestringFarm name
city, statestringLocation
lat, lngnumberCoordinates
productsstring[]Product types carried by this farm
certificationsstring[]e.g. "USDA Organic"
quality_scorenumber0–100 quality signal (Pro tier)
place_typestring"farm", "market", "ranch", "CSA", etc.
distance_minumberDistance from your search center
delivery_optionsstring[]Pickup and delivery methods
websitestringFarm website URL
When meta.has_more is true, request the next page with ?page=2.

​
What’s next