Skip to main content

DocsREST API and MCP server

Farm Data Search API

Endpoints, auth and live samples for Audience Builder, Connect Data and CRM sync.

Base URLhttps://us-farmvision-new-api.onrender.com

Audience Builder: Farm Data Search

Farm Search Count

Counts the farm records that match a filter set; only mail-deliverable records of living producers are counted. Send countBy as an array to get several counts in one request; identical requests may be answered from a short-lived cache. 400 names the field at fault (unknown states are listed in invalidValues), and 429 or 503 mean too many counts are running, so retry shortly.

POSThttps://us-farmvision-new-api.onrender.com/api/v1/farm-search/countTry it

In this section

Authentication

Get API key

Bearer token or partner key

Send your GTM Scoop API key (llmcp_…) as a Bearer token. Partner keys issued by our team go in x-api-key instead, never both. Calls with no credentials get 401.

Authorization: Bearer YOUR_API_KEY
x-api-key: YOUR_PARTNER_KEY

Request body

application/json
FieldTypeDescription
filtersbodyobjectFarm criteria (the filters.* fields below). Omit for the whole dataset. Different fields are AND'd; values inside one field are OR'd. Limits: 5,000 values per list, 500 characters per value.
excludeFiltersbodyobjectSame shape as filters; matching records are left out. A value listed in both is dropped from filters. When this holds any value, filterMode is ignored.
filterModebodystring"include" (default) or "exclude": treat every value in filters as an exclusion instead.
countBybodystring | string[]records (default: farm records), farmers (distinct producers), farmLands (distinct farm locations), ranchers (distinct producers with cattle, dairy, hogs, sheep, goats or horses), poultryFishBees (distinct producers with poultry, fish or bees). An array adds data.counts; data.count is the first one.
filters.statesbodystring[]Full state names ("Iowa") or two-letter codes ("IA"), case-sensitive. District of Columbia is included.
filters.statesNarrowedbodystring[]The selected states that your cities, counties, ZIP codes or radius narrow; the other selected states count whole.
filters.citiesbodystring[]City ids from the Navigator's geography catalog (not names). /ai-criteria resolves city names to these ids.
filters.countiesbodystring[]County ids from the Navigator's geography catalog (not names). /ai-criteria resolves county names to these ids.
filters.zipCodesbodystring[]Five-digit ZIP codes (e.g. "50010"), or catalog ZIP ids.
filters.citiesOutsidebodystring[]City ids in states you have not selected; added to the state selection instead of narrowing it.
filters.countiesOutsidebodystring[]County ids in states you have not selected; added to the state selection instead of narrowing it.
filters.zipCodesOutsidebodystring[]ZIP codes in states you have not selected; added to the state selection instead of narrowing it.
filters.radiusByZipbodyobject{ minLat, maxLat, minLon, maxLon } bounding box (all four required), plus optional centerLat, centerLon and radiusMiles to match a true distance circle instead.
filters.cropsbodystring[]Crop names from /meta crops or otherCrops (e.g. "Corn", "Soybean", "Apple"). Unknown names are ignored.
filters.livestockbodystring[]Cattle, Dairy, Hogs, Sheep, Goats, Horses, Poultry, Fish, Bees.
filters.cattleOutputTypesbodystring[]Cattle categories from /meta cattleOutputTypes (e.g. "Steers", "Bulls"). When set, these replace a plain Cattle pick.
filters.grassTypesbodystring[]Grass/turf uses from /meta grassTypes (e.g. "Grazing", "Turf Sod").
filters.acreRangesbodystring[]Total-acre buckets: 1-9, 10-24, 25-49, 50-99, 100-249, 250-499, 500-999, 1000-2499, 2500-4999, 5000+.
filters.exactAcreRangesbodystring[]"min-max" total acres, e.g. "300-800".
filters.exactAcreComparisonsbodystring[]"op:value" total acres, op = more (at least), less or equal, e.g. "more:500".
filters.primaryAcreFiltersbodyobjectAcres of one crop: { "Corn Acre": ["100 to 249"] }. Keys from /meta primaryAcreCrops, ranges from /meta acreBucketRangeOptions.
filters.secondaryAcreFiltersbodyobjectSame shape for the other-crops list: { "Apple Acre": ["1 to 9"] }. Keys from /meta secondaryAcreCrops.
filters.livestockHeadRangesbodystring[]Total head-count buckets from /meta livestockHeadRangeOptions ("1 - 10" to "5000+", or "Unknown").
filters.livestockHeadFiltersbodyobjectHead count per animal: { "Cattle": ["501 - 1000"] }. Keys: Total, Cattle, Dairy, Goat, Hog, Sheep.
filters.producerTypesbodystring[]Producer types from /meta producerTypes (e.g. "Owner / Operator Producer Type").
filters.entityCodeTypesbodystring[]Entity-type letters A to K; /meta entityCodeLabels names them (A = Individual, D = Corporation With Stockholders, ...).
filters.farmCountRangesbodystring[]Number of farms the producer runs: 1-9, 10-19, 20-39, 40-99, 100-199, 200-299, 300-499, 500+.
filters.ageRangesbodystring[]Producer age: 19-24, 25-34, 35-44, 45-54, 55-64, 65-74, 75+, Unknown.
filters.farmersTypebodystringOne of "Crop Farmers Only", "All Crop Farmers", "Livestock Farmers Only", "All Livestock Farmers". "Only" means that type and not the other.
filters.irrigatebodystring"Yes" or "No".
filters.qualityFiltersbodystring[]Data-quality requirements from /meta qualityFilters (e.g. "100% Phone", "Verified Email", "Omit PO Boxes"). Every one picked must hold.
filters.revenueRangesbodystring[]Estimated revenue bands from /meta revenueRanges (e.g. "$100,001 - $200,000").
filters.exactRevenueRangesbodystring[]"min-max" estimated revenue in dollars, e.g. "1000000-5000000".
filters.revenueComparisonsbodystring[]"op:value" estimated revenue in dollars, op = more (at least), less or equal, e.g. "more:500000".

Mounted at

/api/v1/farm-search

Sizes a farm audience: count the farms and producers that match a filter set, list the values each filter accepts, or turn a plain-language request into filters. Per-minute limits are per caller: 120 for a signed-in session, your plan's rate (plus its daily MCP budget) for an API key, and the issued rate for a partner key.

Try it in the playground

Signed out: 10 free tries a day with names hidden. Log in for live data.

Open playground

Related endpoints

All 3 endpoints in this section

Bearer (API key or session token) or a partner x-api-key; a GTM Scoop request with no credentials gets 401.

MethodPathWhat it does
POST/api/v1/farm-search/count

Farm Search Count

Counts the farm records that match a filter set; only mail-deliverable records of living producers are counted. Send countBy as an array to get several counts in one request; identical requests may be answered from a short-lived cache. 400 names the field at fault (unknown states are listed in invalidValues), and 429 or 503 mean too many counts are running, so retry shortly.

34 parameters
  • filters (object) Farm criteria (the filters.* fields below). Omit for the whole dataset. Different fields are AND'd; values inside one field are OR'd. Limits: 5,000 values per list, 500 characters per value.
  • excludeFilters (object) Same shape as filters; matching records are left out. A value listed in both is dropped from filters. When this holds any value, filterMode is ignored.
  • filterMode (string) "include" (default) or "exclude": treat every value in filters as an exclusion instead.
  • countBy (string | string[]) records (default: farm records), farmers (distinct producers), farmLands (distinct farm locations), ranchers (distinct producers with cattle, dairy, hogs, sheep, goats or horses), poultryFishBees (distinct producers with poultry, fish or bees). An array adds data.counts; data.count is the first one.
  • filters.states (string[]) Full state names ("Iowa") or two-letter codes ("IA"), case-sensitive. District of Columbia is included.
  • filters.statesNarrowed (string[]) The selected states that your cities, counties, ZIP codes or radius narrow; the other selected states count whole.
  • filters.cities (string[]) City ids from the Navigator's geography catalog (not names). /ai-criteria resolves city names to these ids.
  • filters.counties (string[]) County ids from the Navigator's geography catalog (not names). /ai-criteria resolves county names to these ids.
  • filters.zipCodes (string[]) Five-digit ZIP codes (e.g. "50010"), or catalog ZIP ids.
  • filters.citiesOutside (string[]) City ids in states you have not selected; added to the state selection instead of narrowing it.
  • filters.countiesOutside (string[]) County ids in states you have not selected; added to the state selection instead of narrowing it.
  • filters.zipCodesOutside (string[]) ZIP codes in states you have not selected; added to the state selection instead of narrowing it.
  • filters.radiusByZip (object) { minLat, maxLat, minLon, maxLon } bounding box (all four required), plus optional centerLat, centerLon and radiusMiles to match a true distance circle instead.
  • filters.crops (string[]) Crop names from /meta crops or otherCrops (e.g. "Corn", "Soybean", "Apple"). Unknown names are ignored.
  • filters.livestock (string[]) Cattle, Dairy, Hogs, Sheep, Goats, Horses, Poultry, Fish, Bees.
  • filters.cattleOutputTypes (string[]) Cattle categories from /meta cattleOutputTypes (e.g. "Steers", "Bulls"). When set, these replace a plain Cattle pick.
  • filters.grassTypes (string[]) Grass/turf uses from /meta grassTypes (e.g. "Grazing", "Turf Sod").
  • filters.acreRanges (string[]) Total-acre buckets: 1-9, 10-24, 25-49, 50-99, 100-249, 250-499, 500-999, 1000-2499, 2500-4999, 5000+.
  • filters.exactAcreRanges (string[]) "min-max" total acres, e.g. "300-800".
  • filters.exactAcreComparisons (string[]) "op:value" total acres, op = more (at least), less or equal, e.g. "more:500".
  • filters.primaryAcreFilters (object) Acres of one crop: { "Corn Acre": ["100 to 249"] }. Keys from /meta primaryAcreCrops, ranges from /meta acreBucketRangeOptions.
  • filters.secondaryAcreFilters (object) Same shape for the other-crops list: { "Apple Acre": ["1 to 9"] }. Keys from /meta secondaryAcreCrops.
  • filters.livestockHeadRanges (string[]) Total head-count buckets from /meta livestockHeadRangeOptions ("1 - 10" to "5000+", or "Unknown").
  • filters.livestockHeadFilters (object) Head count per animal: { "Cattle": ["501 - 1000"] }. Keys: Total, Cattle, Dairy, Goat, Hog, Sheep.
  • filters.producerTypes (string[]) Producer types from /meta producerTypes (e.g. "Owner / Operator Producer Type").
  • filters.entityCodeTypes (string[]) Entity-type letters A to K; /meta entityCodeLabels names them (A = Individual, D = Corporation With Stockholders, ...).
  • filters.farmCountRanges (string[]) Number of farms the producer runs: 1-9, 10-19, 20-39, 40-99, 100-199, 200-299, 300-499, 500+.
  • filters.ageRanges (string[]) Producer age: 19-24, 25-34, 35-44, 45-54, 55-64, 65-74, 75+, Unknown.
  • filters.farmersType (string) One of "Crop Farmers Only", "All Crop Farmers", "Livestock Farmers Only", "All Livestock Farmers". "Only" means that type and not the other.
  • filters.irrigate (string) "Yes" or "No".
  • filters.qualityFilters (string[]) Data-quality requirements from /meta qualityFilters (e.g. "100% Phone", "Verified Email", "Omit PO Boxes"). Every one picked must hold.
  • filters.revenueRanges (string[]) Estimated revenue bands from /meta revenueRanges (e.g. "$100,001 - $200,000").
  • filters.exactRevenueRanges (string[]) "min-max" estimated revenue in dollars, e.g. "1000000-5000000".
  • filters.revenueComparisons (string[]) "op:value" estimated revenue in dollars, op = more (at least), less or equal, e.g. "more:500000".
Try Farm Search Count in the Playground
GET/api/v1/farm-search/meta

Farm Search Filter Options

Lists the values each farm filter accepts, so you can build a filter set without guessing. The lists don't change between requests: fetch once and cache them.

Try Farm Search Filter Options in the Playground
POST/api/v1/farm-search/ai-criteria

Farm AI Criteria

Turns a plain-language request into farm filters you can pass straight to /count (it returns filters, not a count); place names are resolved to geography ids, and anything it couldn't map comes back in unmatched. Shares one AI criteria budget with Business and Property, by default 20 requests a minute and 300 a day per account, or 50 a day without an active Navigator subscription (429 with code AI_RATE_LIMIT or AI_DAILY_LIMIT). 502 means generation failed: retry.

2 parameters
  • text (string, required) The request in plain language, up to 2,000 characters.
  • hintStates (string[]) States already selected. Helps resolve a city or county name that exists in several states.
Try Farm AI Criteria in the Playground

Cookies on GTM Scoop

Essential cookies keep you signed in and the site secure, and are always on. Optional cookies (Google Analytics) help us understand how the site is used. They are on by default, except in the EU/EEA, the UK and Switzerland, where they stay off until you choose Accept All Cookies; choose Essential Cookies Only to turn them off. We do not use advertising cookies and we do not sell or share your personal information. The site works the same whichever you choose. We keep a record of your choice with the date, your IP address and the page you were on. Cookie Policy · Privacy Policy