TownVue Public API
60 mi
5 mi500 mi

TownVue Public API

A read-only JSON API designed for AI agents and integrators. Returns the same business, event, experience, trading-post, town, and category data that powers www.townvue.com, in clean JSON, over HTTPS, with no authentication.

Interactive docs (Swagger UI) OpenAPI spec Mirror at /public-api/v1/openapi.json

The basics

Base URL
/public-api/v1
Auth
None
Format
JSON
Rate limit (burst)
60 req/min/IP
Rate limit (daily)
5,000 req/day/IP
Pagination cap
20 pages × 50 items
CORS
Any origin (GET)
Caching
5 min default

Endpoints

Businesses

GET /public-api/v1/businesses Search by city, state, category. Paginated.
GET /public-api/v1/businesses/{slug-id} Detail by public slug-id (e.g. acme-plumbing-42).

Events

GET /public-api/v1/events Upcoming by default. city, state, from, to filters.
GET /public-api/v1/events/{slug-id} Event detail with full description, location, organizer info.

Experiences

GET /public-api/v1/experiences Search active experiences by city or state.
GET /public-api/v1/experiences/{slug-id} Experience detail.

Trading Post

GET /public-api/v1/trading-post Active, unsold marketplace listings.
GET /public-api/v1/trading-post/{slug-id} Trading-post listing detail.

Towns & categories

GET /public-api/v1/towns Towns covered, with content-type counts.
GET /public-api/v1/towns/{city-slug} Single town detail (e.g. powell-oh).
GET /public-api/v1/categories Active business-category taxonomy.

Example

curl -s "https://www.townvue.com/public-api/v1/businesses?city=Powell&state=OH&pageSize=5" \
  -H "Accept: application/json"

Privacy & data scope

The API exposes only what is already publicly visible on www.townvue.com:

  • Business hours, address, phone, email, website are returned only when the owner has marked them public.
  • No personally-identifying information about TownVue users is ever returned. Community-article authorship is exposed as PublicName only and only when the user has set one.
  • No internal IDs, admin fields, or moderation flags. Slug-ids are stable public identifiers.
  • Inactive, admin-disabled, or unapproved listings are excluded from search and 404 on detail.

Rate limits and pagination

Two independent caps both apply to every request:

  • 60 requests per minute per remote IP (sliding window).
  • 5,000 requests per day per remote IP (rolling 24-hour window).

Exceeding either limit returns 429 Too Many Requests with a Retry-After header.

Search endpoints additionally cap pagination at 20 pages. Combined with the 50-item-per-page maximum, that returns up to 1,000 records for any single query. Need more results? Narrow the query with city, state, or category filters and paginate within each scope. Returning the full catalog from a single broad query isn't a supported use case; use the sitemap or JSON feeds for catalog discovery.

Need higher rate limits or programmatic access for a real integration? Email support@townvue.com with your use case. See Terms of Service for the bulk-extraction policy.

Stability and versioning

This is the v1 contract. Backwards-incompatible changes get a new version under /public-api/v2/; v1 remains stable. Additive changes (new optional fields) may land within v1. The OpenAPI spec at /.well-known/openapi.json is the authoritative contract.

Editorial disclosure

For how content gets onto TownVue, how errors get corrected, and how facts get verified, see our editorial standards. Our About page describes the company behind the API.