Présentation de l'API

Things to Do API propose une interface REST permettant de rechercher des manifestations culturelles, commerciales ou communautaires à l’échelle d’une ville. Le service se décrit comme « fast, accurate, localized events API for agentic applications », ce qui indique une priorité sur la latence et la pertinence géographique. L’exemple fourni montre une requête curl qui interroge le point d’accès https://api.thingstodoapi.com/v1/search avec les paramètres q=comedy+in+san+francisco+this+weekend. La réponse JSON contient les champs title, category, starts_at, local (date et heure lisibles), venue (nom et ville) et links (source et billetterie). Cette structure montre que l’API restitue à la fois des métadonnées structurées et des URL exploitables par des agents automatisés.

curl "https://api.thingstodoapi.com/v1/search?q=comedy+in+san+francisco+this+weekend"
{
  "title": "Drag-Up Comedy",
  "category": "arts",
  "starts_at": "2026-10-19T02:00:00.000Z",
  "local": {
    "date": "2026-10-18",
    "time": "7:00 PM"
  },
  "venue": {
    "name": "Cobb's Comedy Club",
    "city": "San Francisco"
  },
  "links": {
    "source": "https://www.ticketmaster.com/dragup-comedy-san-francisco-california-10-18-2026/event/1C0064D823FC0B87",
    "tickets": "https://ticketmaster.evyy.net/c/253185/264167/4272?SharedId=DoStuff&u=https%3A%2F%2Fwww.ticketmaster.com%2Fdragup-comedy-san-francisco-california-10-18-2026%2Fevent%2F1C0064D823FC0B87"
  }
}

Architecture et protocoles

L’API repose sur le protocole HTTP standard, avec une méthode GET pour le point d’accès /v1/search. Aucun corps de requête n’est requis, ce qui simplifie l’intégration côté client. Le service expose également un « MCP » (Machine‑Client Protocol) compatible avec Claude, comme le montre la commande claude mcp add --transport http thingstodo https://api.thingstodoapi.com/mcp. Cette double exposition (REST + MCP) indique que le fournisseur cible à la fois les développeurs traditionnels et les agents conversationnels capables d’interpréter des flux de données via un transport HTTP.

Les réponses sont encodées en JSON, format largement supporté par les bibliothèques de parsing. Les champs temporels utilisent le format ISO‑8601 (2026-10-19T02:00:00.000Z), ce qui facilite la conversion en fuseaux horaires locaux. Le champ local fournit une version « human‑readable » de la date et de l’heure, ce qui peut être exploité directement par des interfaces utilisateur sans transformation supplémentaire.

Analyse des performances et limites

Le descriptif « fast » repose probablement sur une infrastructure de recherche géospatiale optimisée, mais la source ne fournit pas de métriques de latence ou de capacité de charge. L’absence de paramètres de pagination dans l’exemple suggère que le service renvoie un nombre limité d’événements par requête, ce qui pourrait restreindre les scénarios de découverte massive. Aucun indicateur de taux d’erreur, de quotas d’utilisation ou de mécanismes d’authentification n’est mentionné, ce qui laisse une zone d’incertitude pour les intégrations en production.

Du point de vue de la sécurité, le transport HTTP est indiqué sans chiffrement explicite (HTTPS est implicite dans l’URL). La documentation ne précise pas de mécanisme d’authentification (API‑key, OAuth), ce qui signifie que l’accès public pourrait être sujet à des abus si aucune limitation côté serveur n’est appliquée. Enfin, la dépendance à des sources externes comme Ticketmaster pour les liens de billetterie introduit une variable de disponibilité hors du contrôle de l’API.