Foundly Data API · v1

Ground your models in the real local economy.

One request returns a clean, ranked, freshness-stamped map of a local market — who's there, what they do, and how current every fact is. No scraping fifty sites. No guessing.

Request
GET /api/v1/market-grid
  ?lat=33.494&lng=-111.926
  &service=microneedling
Authorization: Bearer fdly_live_•••
↓
Response · fresh
{
  "market": {
    "category": "med-spa",
    "city": "Scottsdale",
    "business_count": 3,
    "market_total": 41
  },
  "freshness": {
    "state": "fresh",
    "age_seconds": 4120
  },
  "businesses": [
    {
      "name": "Radiance MedSpa",
      "rank": 1,
      "score": 87.4,
      "sov_pct": 22.1,
      "services": {
        "verified": ["PRP Microneedling"],
        "detected": ["Botox", "Facials"]
      }
    }
  ]
}
Quickstart

Your first call, in three steps

01
Get a key

Business owners generate a key from the API Access tab in the dashboard. Data partners request one from our team.

02
Authenticate

Pass your key as a bearer token on every request. Keep it server-side — treat it like a password.

03
Query a market

Hit /v1/market-grid with a coordinate or a city, and read the clean JSON back.

curl -s "https://tryfoundly.com/api/v1/market-grid\
?lat=33.494&lng=-111.926&service=microneedling" \
  -H "Authorization: Bearer $FOUNDLY_KEY"
Authentication

One key, scoped to what you can see

Every request carries an Authorization: Bearer header. Your key's scope decides what it reaches — a business key returns only that business, a partner key reads the market index. We store only a hash of your key, so a leak on our side never exposes a usable credential.

Authorization: Bearer fdly_live_a1b2c3d4e5f6...
Business keys

Self-serve from your dashboard. Scoped to your own business, included with your plan.

Partner keys

For AI labs and data teams reading the market index in bulk. Issued by our team.

Endpoints

Five endpoints, one clean shape

GET
/v1/market-grid

A ranked, freshness-stamped snapshot of one local market. Resolve by coordinate, category + city, or cluster id. Filter to a single service.

GET
/v1/bulk/markets

Stream every market as NDJSON for batch ingestion. Cursor-paginated, with delta sync via ?since= to pull only what changed.

GET
/v1/freshness

Coverage and freshness telemetry — verify how current the data is before you pull it. No business data, just the trust layer.

GET
/v1/business

Your own business's visibility telemetry. The key is bound to one business and returns only its data.

GET
/v1/usage

Your API consumption — lifetime and by-month call counts, broken down by endpoint.

Full API reference →API statusChangelog