Monterey County Event Directory

API & embed

API and embed

Public read API

GET /api/v1/events returns upcoming published events as JSON.

Query parameters: region (slug, repeatable), category (slug, repeatable), from and to (YYYY-MM-DD, local dates), q (keyword), free (1), page (1-based, 40 per page).

GET /api/v1/events/{slug} returns one event with all occurrences.

Responses include a meta.attribution string. Attribution is required wherever you display the data: show "via Monterey County Event Directory" with a link to the event page. The API is rate-limited; cache responses for at least 5 minutes.

Data partner access

Partners who sync the whole directory (tourism boards, newsrooms, apps) get a partner key from us; write to us through the contact page. Send it as Authorization: Bearer med_... on GET /api/v1/events. Partner keys add:

  • updated_since (ISO 8601 instant, e.g. 2026-11-01T00:00:00Z): only events or dates changed since then, including cancellations (status: "cancelled"), so you can sync incrementally. Every item carries updated_at.
  • per_page up to 500 (the public limit is 40), with meta.total_pages and meta.next.
  • format=ndjson for bulk export: one JSON object per line, with X-Total-Count and a Link: <...>; rel="next" header.
  • A higher hourly limit (5,000 requests by default, versus 120 for organizer keys).

All filters above (region, category, from, to, q, free) still apply. Responses to keyed requests carry X-RateLimit-Limit and X-RateLimit-Remaining; above the limit you get 429. Using a partner-only parameter without a key returns 401; with a non-partner key, 403 partner_tier_required.

curl "https://YOUR-SITE/api/v1/events?updated_since=2026-11-01T00:00:00Z&from=2026-11-01&to=2027-10-31&per_page=500&format=ndjson" \
  -H "Authorization: Bearer med_xxxxxxxx"

Calendar feeds

Every list on this site is also an iCalendar feed: /cal/all.ics, /cal/region/{slug}.ics, /cal/category/{slug}.ics, /cal/organization/{slug}.ics, /cal/venue/{slug}.ics, /cal/this-weekend.ics. Single events: /cal/event/{slug}.ics. RSS: /feeds/events.rss, /feeds/region/{slug}.rss, /feeds/category/{slug}.rss.

Push API

Organizers can create and update their own events from their website, CRM or Zapier/Make. Create a key in Dashboard → API keys; keys are scoped to one organization and shown once.

POST /api/v1/events with Authorization: Bearer med_... and a JSON body:

{
  "external_id": "mixer-2026-11",
  "title": "November Business Mixer",
  "summary": "Monthly networking mixer for members and guests.",
  "description": "Appetizers and a no-host bar. Markdown is fine.",
  "starts": { "date": "2026-11-12", "time": "17:30" },
  "ends": { "date": "2026-11-12", "time": "19:00" },
  "all_day": false,
  "additional_dates": ["2026-12-10"],
  "recurrence_text": "",
  "venue_name": "Portola Hotel & Spa",
  "address": "2 Portola Plaza",
  "city": "Monterey",
  "is_virtual": false,
  "price_text": "Free for members, $20 guests",
  "is_free": false,
  "urls": { "registration": "https://example.org/mixer", "more_info": "https://example.org/events/mixer" },
  "image_url": "https://example.org/mixer.jpg",
  "categories": ["business-networking", "chamber-events"],
  "audience_tags": ["business-professional"],
  "expected_attendance": 80
}

Rules:

  • external_id is your stable id. Posting the same external_id again updates the event (200) instead of creating a duplicate (201). Dates removed from an update are marked cancelled so calendar subscribers are told.
  • Dates and times are Pacific local time (YYYY-MM-DD, HH:MM). Use recurrence_text ("Every Tuesday", "Second Thursday of the month") for repeating events; we expand twelve months ahead.
  • categories and audience_tags are slugs from /categories and the audience list on /plan.
  • Verified organizations publish immediately; unverified ones go to review.
  • Responses: 201/200 { data: { id, slug, url, status, occurrences, external_id } }, 422 with issues[] for validation errors, 401/403 for key problems, 429 above your key's hourly limit (120 requests per hour for organizer keys).

Example:

curl -X POST https://YOUR-SITE/api/v1/events \
  -H "Authorization: Bearer med_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"mixer-2026-11","title":"November Business Mixer","starts":{"date":"2026-11-12","time":"17:30"},"venue_name":"Portola Hotel & Spa","city":"Monterey","categories":["business-networking"]}'

Bulk? Use Dashboard → CSV import (template provided; same columns as the fields above).

Embed widget

Show your organization's upcoming events on your own site:

<script src="https://YOUR-SITE/embed.js" data-org="your-organization-slug" async></script>

Optional attributes: data-limit="5", data-theme="compact". The script inserts an auto-sizing iframe of server-rendered HTML (/embed/org/{slug}) with a small "Powered by" link; no cookies, no tracking scripts. Prefer an iframe? Point it at /embed/org/{slug}?limit=8.