Data Machine Events exposes a focused REST surface under the datamachine/v1 namespace. Each route is registered in inc/Api/Routes.php and handled by the controllers in inc/Api/Controllers so the Calendar and Event Details blocks plus admin UI stay synchronized with SQL-powered filtering.

Architecture

• Base URL: /wp-json/datamachine/v1/
• Route registration: inc/Api/Routes.php maps resources to Calendar, Filters, Venues, and Geocoding controllers.
• Controller responsibilities:
  • Calendar handles event queries, HTML fragment rendering, pagination, and counter updates used by the Calendar block and JS modules.
  • Filters builds taxonomy hierarchies, counts, and dependency hints for the filter modal.
  • Venues surfaces venue metadata (and duplicate checks) to admin flows.
  • Geocoding proxies OpenStreetMap Nominatim lookups for venue creation.
• Security & sanitization: Every route sanitizes inputs using sanitize_text_field, absint, sanitize_key, or custom callbacks, enforces capability checks where required, and returns standardized JSON responses.
• Progressive enhancement: Calendar block falls back to server-rendered templates; REST responses simply replace fragments when JavaScript is active.

Endpoints

GET /wp-json/datamachine/v1/events/calendar

• Calendar handles event queries, HTML fragment rendering, pagination, and counter updates used by the Calendar block and JS modules.
• Filters builds taxonomy hierarchies, counts, and dependency hints for the filter modal.
• Venues surfaces venue metadata (and duplicate checks) to admin flows.
• Geocoding proxies OpenStreetMap Nominatim lookups for venue creation.

GET /wp-json/datamachine/v1/events/filters

• Calendar handles event queries, HTML fragment rendering, pagination, and counter updates used by the Calendar block and JS modules.
• Filters builds taxonomy hierarchies, counts, and dependency hints for the filter modal.
• Venues surfaces venue metadata (and duplicate checks) to admin flows.
• Geocoding proxies OpenStreetMap Nominatim lookups for venue creation.

GET /wp-json/datamachine/v1/events/venues/{id}

• Purpose: Supplies calendar HTML fragments (html, pagination, navigation, counter) for the Calendar block while keeping server-side pagination/accounting.
• Controller: Calendar::calendar().
• Arguments:
  • event_search (string): Free text search.
  • date_start / date_end (YYYY-MM-DD): Bound the query range.
  • tax_filter (object): Map of { taxonomy: [termId, ...] }.
  • archive_taxonomy (string): Sanitized taxonomy key for archive context.
  • archive_term_id (int): Term ID for archive context.
  • paged (int): Page number.
  • past (string): Past-event toggle.
• Behavior: Sanitizes every argument, builds SQL-based WP_Query filters (dates, _datamachine_event_datetime, taxonomies), caches taxonomy counts via helper classes, and returns success + fragments for frontend replacement.

GET /wp-json/datamachine/v1/events/venues/check-duplicate

• event_search (string): Free text search.
• date_start / date_end (YYYY-MM-DD): Bound the query range.
• tax_filter (object): Map of { taxonomy: [termId, ...] }.
• archive_taxonomy (string): Sanitized taxonomy key for archive context.
• archive_term_id (int): Term ID for archive context.
• paged (int): Page number.
• past (string): Past-event toggle.

POST /wp-json/datamachine/v1/events/geocode/search

• event_search (string): Free text search.
• date_start / date_end (YYYY-MM-DD): Bound the query range.
• tax_filter (object): Map of { taxonomy: [termId, ...] }.
• archive_taxonomy (string): Sanitized taxonomy key for archive context.
• archive_term_id (int): Term ID for archive context.
• paged (int): Page number.
• past (string): Past-event toggle.

Notes

• Purpose: Provides taxonomy term data (counts, parents, dependencies) for the Calendar filter modal.
• Controller: Filters::get().
• Arguments:
  • active (object): Map of { taxonomy: [termId, ...] }.
  • context (string): Defaults to modal.
  • date_start / date_end (string)
  • past (string)
• Behavior: Sanitizes keys/values, computes term counts for the current calendar context, respects data_machine_events_excluded_taxonomies, and responds with structured metadata used by the Calendar block modal.