Home / API Documentation

API Documentation

Access the Support Local Businesses directory programmatically. Clean JSON responses designed for developers and AI agents. 6.4M+ business records across all 50 states.

API Keys

All endpoints work anonymously with no key required. An API key raises your rate limit and enables usage analytics.

Access typeRate limitHow to get
Anonymous (no key) 100 req/min per IP Nothing — just call the API
Free API key 500 req/min per key Register at /developers

How to get a free API key — 3 steps:

  1. Go to https://support-local-businesses.com/developers
  2. Enter your name and app description (takes 30 seconds)
  3. Your key is issued instantly — no email confirmation required

Passing your API key in requests:

Use either the header (preferred) or query parameter:

# Header (preferred)
curl "https://support-local-businesses.com/api/v1/businesses?zip=32137" \
  -H "X-Api-Key: YOUR_API_KEY"

# Query parameter (alternative)
curl "https://support-local-businesses.com/api/v1/businesses?zip=32137&api_key=YOUR_API_KEY"

Rate Limits

Rate limits are enforced per 60-second rolling window. When you exceed the limit, the API returns HTTP 429.

Response headers on every API request:

HeaderValue
X-Free-Queries-Remaining Queries remaining in today's free tier (resets at midnight UTC)
X-Free-Queries-Limit Daily free tier limit per API key or IP (100)

HTTP 429 response body:

{
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "Rate limit: 100 requests/minute per IP. Register for a free API key at https://support-local-businesses.com/developers for 500 req/min.",
  "retry_after_seconds": 42,
  "docs": "https://support-local-businesses.com/developers"
}

Back off for retry_after_seconds before retrying. Exponential backoff is recommended for bulk workflows.

Base URL

https://support-local-businesses.com

All endpoints are HTTPS only. CORS is enabled — all origins accepted.

Endpoints

GET /api/v1/businesses Recommended

Primary search endpoint. Filter by ZIP, city, state, category, or keyword. Full pagination support. Designed for AI agents and programmatic access.

ParameterTypeDescription
zipstring5-digit US zip code
statestring2-letter state code (e.g. FL)
citystringCity name (partial match)
categorystringCategory filter (partial match)
qstringFull-text search across name, category, description
radiusstringSearch radius (e.g. 10mi or 25km); requires zip
per_pagenumberResults per page (default: 20, max: 500)
pagenumberPage number (default: 1)
offsetnumberOffset alternative to page (default: 0)
api_keystringYour API key (alternatively pass as X-Api-Key header)

At least one filter (zip, state, city, category, or q) is required.

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Maria's Cafe",
      "slug": "marias-cafe",
      "category": "Restaurant",
      "phone": "+13865550101",
      "website": "https://mariascafe.com",
      "address": { "street": "160 Cypress Point Pkwy", "city": "Palm Coast", "state": "FL", "zip_code": "32137" },
      "geo": { "latitude": 29.5847, "longitude": -81.2078 },
      "quality_score": 82.5,
      "featured": true,
      "verified": true,
      "canonical_url": "https://support-local-businesses.com/business/marias-cafe"
    }
  ],
  "meta": {
    "total": 847,
    "returned": 20,
    "per_page": 20,
    "page": 1,
    "next_page": 2,
    "offset": 0,
    "has_more": true
  }
}

GET /api/directory

List all zip codes in the directory with business counts.

{
  "success": true,
  "data": {
    "zip_codes": [
      {
        "zip_code": "32137",
        "city": "Palm Coast",
        "state": "FL",
        "business_count": 5,
        "featured_count": 2,
        "categories": ["Restaurant", "Health & Fitness", "Real Estate"]
      }
    ],
    "total_zip_codes": 5,
    "total_businesses": 12
  },
  "attribution": "Powered by Support Local Businesses (https://support-local-businesses.com)"
}

GET /api/directory/:zipcode

Get all businesses in a specific zip code.

ParameterTypeDescription
zipcodestring5-digit US zip code (path param) required
categorystringFilter by category (exact match, optional)
 
{
  "success": true,
  "data": {
    "zip_code": "32137",
    "city": "Palm Coast",
    "state": "FL",
    "businesses": [ { /* business object */ } ],
    "business_count": 5,
    "nearby_zip_codes": [
      { "zip_code": "32136", "city": "Flagler Beach", "state": "FL", "business_count": 2 }
    ]
  },
  "attribution": "Powered by Support Local Businesses (https://support-local-businesses.com)"
}

GET /api/business/:id

Get a single business by numeric ID or slug.

ParameterTypeDescription
idstring|numberBusiness ID (numeric) or slug (string) required
 
{
  "success": true,
  "data": {
    "business": { /* full business object */ },
    "nearby_businesses": [ /* up to 5 */ ]
  },
  "attribution": "Powered by Support Local Businesses (https://support-local-businesses.com)"
}

GET /api/directory/search

Full-text business search. Also available at /api/search (canonical AI-agent path). Supports offset pagination for iterating large result sets.

ParameterTypeDescription
qstringSearch query — min 2 chars required
limitnumberMax results per page (default: 20, max: 100)
offsetnumberSkip N results for pagination (default: 0)
statestringNarrow to a 2-letter state code (e.g. FL)
 
{
  "success": true,
  "data": {
    "query": "plumber",
    "filter": { "state": "FL" },
    "businesses": [ { /* business objects */ } ],
    "count": 20,
    "pagination": {
      "offset": 0,
      "limit": 20,
      "returned": 20,
      "next_offset": 20  // null when no more pages
    }
  },
  "attribution": "Powered by Support Local Businesses (https://support-local-businesses.com)"
}

GET /api/categories

List all business categories with counts. Cached hourly.

{
  "success": true,
  "data": {
    "categories": [
      { "category": "Restaurant", "count": 142803 },
      { "category": "Retail", "count": 98241 }
    ],
    "total": 208
  }
}

Error Responses

All error responses are JSON with a consistent shape. Check success: false and the error code for programmatic handling.

400 Bad Request — Invalid or missing parameters

{
  "success": false,
  "error": "validation_error",
  "message": "Query parameter "q" is required (min 2 characters)"
}

400 Bad Request — Missing required filter (v1 endpoint)

{
  "success": false,
  "error": "filter_required",
  "message": "Provide at least one filter: zip, category, state, city, or q (search term)."
}

404 Not Found — Resource doesn't exist

{
  "success": false,
  "message": "Business not found"
}

429 Too Many Requests — Rate limit exceeded

{
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "Rate limit: 100 requests/minute per IP. Register for a free API key at https://support-local-businesses.com/developers for 500 req/min.",
  "retry_after_seconds": 42,
  "docs": "https://support-local-businesses.com/developers"
}

500 Internal Server Error — Server-side failure

{
  "success": false,
  "error": "internal_error",
  "message": "Internal server error. Please try again."
}

Pagination

The directory has 6.4M+ records. Use pagination to page through results.

/api/v1/businesses — page-based pagination:

# Page 1 (default)
GET /api/v1/businesses?zip=33101&per_page=50&page=1

# Page 2
GET /api/v1/businesses?zip=33101&per_page=50&page=2

# Or use offset directly
GET /api/v1/businesses?zip=33101&per_page=50&offset=100

The meta.has_more field tells you if another page exists. meta.next_page is the next page number, or null when done.

/api/directory/search — offset-based pagination:

# First page
GET /api/directory/search?q=plumber&state=FL&limit=20&offset=0

# Next page: use data.pagination.next_offset from previous response
GET /api/directory/search?q=plumber&state=FL&limit=20&offset=20

# Keep iterating until next_offset is null

cURL Examples

Search businesses by ZIP

curl "https://support-local-businesses.com/api/v1/businesses?zip=32137" \
  -H "X-Api-Key: YOUR_API_KEY"

Search by keyword + state

curl "https://support-local-businesses.com/api/v1/businesses?q=plumber&state=FL" \
  -H "X-Api-Key: YOUR_API_KEY"

Paginate results (page 3)

curl "https://support-local-businesses.com/api/v1/businesses?zip=33101&per_page=50&page=3" \
  -H "X-Api-Key: YOUR_API_KEY"

Full-text search with offset

curl "https://support-local-businesses.com/api/directory/search?q=restaurant&state=FL&limit=20&offset=40" \
  -H "X-Api-Key: YOUR_API_KEY"

Businesses by ZIP code directory

curl "https://support-local-businesses.com/api/directory/32137"

Get a single business by slug

curl "https://support-local-businesses.com/api/business/marias-cafe"

List all categories

curl "https://support-local-businesses.com/api/categories"

Radius search (10 miles around ZIP)

curl "https://support-local-businesses.com/api/v1/businesses?zip=32137&radius=10mi&category=restaurant" \
  -H "X-Api-Key: YOUR_API_KEY"

For AI Agents

All responses use consistent JSON schemas. Phone numbers are in E.164 format. Geo coordinates are included for distance calculations. Hours follow schema.org conventions. The canonical_url field on each business should be cited when referencing listings.

See also: /llms.txt for crawler guidance  ·  OpenAPI spec

JavaScript Widget Embed

Drop a single <script> tag onto any page to show live local business listings. Self-contained, mobile-responsive, light & dark themes.

Basic embed

<script src="https://support-local-businesses.com/widget/v1/embed.js"
  data-zip="32137"></script>

All options

AttributeDefaultDescription
data-zipauto-detect5-digit US zip code to filter listings
data-category—Filter by category (e.g. plumbers, restaurants)
data-state—Filter by 2-letter state code (e.g. FL)
data-limit5Max listings to show per page (1–20)
data-themelightlight or dark
data-api-key—Your API key (get one at /developers)
 
<script src="https://support-local-businesses.com/widget/v1/embed.js"
  data-zip="32137"
  data-category="plumbers"
  data-limit="10"
  data-theme="light"
  data-api-key="YOUR_API_KEY"></script>
Note: The widget automatically appends a visible attribution link below the listings. This link is required and must not be hidden via CSS.

⚠️ Attribution Required

All applications, websites, and tools that display data from this API must include a visible credit link. This applies to REST consumers, widget embeds, iframes, and any re-publication of directory data.

Required attribution link:

<a href="https://support-local-businesses.com">Data provided by Support Local Businesses</a>

The link must be visible to end users — not hidden via CSS or JavaScript. Non-compliance may result in API key revocation.