gemeente.leet.onl

gemeente.leet.onl — API & MCP

Volledige koppelingsbeschrijving voor de InUden-app (en elke andere "In…"-app) en voor het vullen van data via MCP of de beheer-API.

  • Basis-URL API: https://gemeente.leet.onl/api/v1
  • MCP-server: https://gemeente.leet.onl/mcp
  • Beheer: https://gemeente.leet.onl/admin
  • Publieke webpagina per plaats: https://gemeente.leet.onl/{slug} (bv. /uden)

1. Concepten

Plaats (tenant). Elke app hoort bij één plaats met een slug (uden, later volkel, odiliapeel, …). Alle publieke data hangt onder /places/{slug}. Een app is dus generiek: hij krijgt de slug mee (build-config) en haalt naam, kleuren, logo en ingeschakelde modules op uit GET /places/{slug}. Zo bouw je één app-codebase en maak je per plaats een eigen build (InUden, InVolkel, …).

Modules. Per plaats aan/uit: businesses, events, organizations, volunteering, news, info, waste. Toon in de app alleen tabs voor modules in place.modules. Een uitgeschakelde module geeft 404 op zijn endpoints.

Voorkomens (occurrences). Herhalende evenementen (wekelijks, "elke 2e dinsdag", …) worden door de API uitgeklapt tot losse voorkomens. Elk voorkomen heeft hetzelfde id (het event) maar een eigen occurrence_id ({id}_{YYYYMMDD}) en eigen starts_at/ends_at. Gebruik occurrence_id als unieke sleutel in lijsten. Aanmelden (RSVP) gebeurt per voorkomen (date).


2. Conventies

Onderwerp Afspraak
Formaat JSON. Stuur altijd Accept: application/json mee.
Wrapper Antwoorden staan in {"data": …}. Lijsten met paginering hebben ook links en meta (current_page, last_page, per_page, total).
Datums ISO 8601 met offset, tijdzone Europe/Amsterdam: 2027-01-12T19:00:00+01:00. Invoer mag ook 2027-01-12 19:00.
Afbeeldingen Volledige URL's (image_url, logo_url) of null.
HTML description, body en info-body bevatten eenvoudige HTML (<p>, <strong>, <ul>, <a>). Render in de app met een HTML/attributed-string renderer.
Lege waarden Velden zijn altijd aanwezig; onbekend = null, lege lijsten = [], lege objecten = {}.
Rate limits Publiek 120 req/min per IP · login/registratie 10/min · MCP 300/min. Bij overschrijding 429 met Retry-After.

Foutcodes

Code Betekenis Body
401 Geen/ongeldige token {"message":"Unauthenticated."}
403 Geen rechten {"message":"…"}
404 Niet gevonden, of module staat uit {"message":"…"}
422 Validatie of bedrijfsregel (vol, verkeerde datum) {"message":"…","errors":{"veld":["…"]}}
429 Te veel verzoeken —

3. Publieke endpoints (geen login)

3.1 Plaats & startscherm

GET /places

Alle actieve plaatsen (voor een eventuele plaats-kiezer).

GET /places/{slug}

App-configuratie. Haal dit op bij app-start en cache het.

{
  "data": {
    "id": 1, "slug": "uden", "name": "Uden", "app_name": "InUden",
    "tagline": "Alles in Uden, in één app",
    "description": "…",
    "colors": { "primary": "#C8102E", "accent": "#1F2937" },
    "logo_url": null, "hero_image_url": null,
    "location": { "lat": 51.66, "lng": 5.617 },
    "contact_email": "info@leet.onl", "website": "https://gemeente.leet.onl/uden",
    "modules": ["businesses","events","organizations","volunteering","news","info","waste"],
    "settings": {},
    "web_url": "https://gemeente.leet.onl/uden"
  }
}

settings is een vrij object dat je in het beheer per plaats vult (bv. {"appstore_url": "…", "min_app_version": "1.2"}) — handig voor feature flags zonder app-update.

GET /places/{slug}/home

Alles voor het startscherm in één call:

{
  "data": {
    "place": { …zie hierboven… },
    "featured_events": [ Event, … ],      // max 5, komende 60 dagen, is_featured
    "upcoming_events": [ Event, … ],      // max 8, komende 60 dagen
    "news": [ NewsPost, … ],              // max 5, vastgezette eerst
    "featured_businesses": [ Business, … ], // max 6, willekeurig
    "volunteering": [ Volunteer, … ],     // max 4, nieuwste
    "next_waste": [ { "date": "2026-11-24", "type": "gft", "label": "GFT", "color": "#2E7D32", "area": null } ]
  }
}

GET /places/{slug}/search?q={term}

Zoekt (min. 2 tekens) over bedrijven, events (komend jaar), verenigingen en nieuws: {"data": {"businesses": [], "events": [], "organizations": [], "news": []}}

GET /places/{slug}/categories?type={type}

type: business · event · organization · volunteer · news. Elke categorie: id, type, name, slug, icon, color. icon is een SF Symbol-naam (bv. fork.knife); map op Android naar een Material-icoon (of gebruik een eigen mapping-tabel).

3.2 Bedrijvengids

GET /places/{slug}/businesses

Query Omschrijving
category categorie-slug of id
q zoek in naam, omschrijving, tags
featured=1 alleen uitgelicht
open_now=1 alleen nu geopend (ongepagineerd)
page, per_page (max 100, standaard 50) paginering

GET /places/{slug}/businesses/{slug|id}

{
  "data": {
    "id": 1, "slug": "museum-krona", "name": "Museum Krona",
    "short_description": "…", "description": "<p>…</p>",
    "category": { "id": 5, "type": "business", "name": "Cultuur & uitgaan", "slug": "cultuur-uitgaan", "icon": "theatermasks", "color": "#AD1457" },
    "image_url": null, "logo_url": null,
    "address": "Veghelsedijk 1", "postal_code": "5401 PA", "city": "Uden",
    "location": { "lat": 51.65, "lng": 5.62 },
    "phone": null, "email": null, "website": "https://www.museumkrona.nl",
    "opening_hours": [ { "day": 2, "open": "11:00", "close": "17:00" } ],
    "is_open_now": true,
    "tags": [], "socials": { "instagram": "https://…" },
    "is_featured": true
  }
}

opening_hours.day: 1 = maandag … 7 = zondag; meerdere slots per dag mogelijk (middagpauze). is_open_now: true/false, of null als er geen tijden bekend zijn. description zit alleen in de detail-call.

3.3 Evenementen & agenda

GET /places/{slug}/events

Query Omschrijving
from, to YYYY-MM-DD, standaard vandaag t/m +90 dagen, max 400 dagen
category slug of id
organization slug of id
featured=1 alleen uitgelicht
page, per_page (max 100, standaard 30) paginering

Antwoord: {"data": [Event…], "meta": {"from","to","page","per_page","total"}}, gesorteerd op starttijd.

Event-object:

{
  "id": 3,
  "occurrence_id": "3_20270112",
  "slug": "repair-cafe",
  "title": "Repair Café",
  "summary": "…",
  "description": "<p>…</p>",
  "image_url": null,
  "starts_at": "2027-01-12T19:00:00+01:00",
  "ends_at": "2027-01-12T21:30:00+01:00",
  "all_day": false,
  "recurrence": "monthly_nth_weekday",
  "recurrence_label": "Elke 2e dinsdag van de maand",
  "location_name": "Buurthuis", "address": null, "location": null,
  "price": "Gratis", "ticket_url": null,
  "status": "published",            // of "cancelled" → toon doorgestreept/label
  "is_featured": false,
  "max_attendees": null,
  "category": { … }, "organization": { "id": 1, "slug": "…", "name": "…", "logo_url": null },
  "attendees": { "going": 4, "interested": 2 },   // voor dít voorkomen
  "my_rsvp": null                    // "going" | "interested" | null (alleen met token)
}

GET /places/{slug}/events/{id}?date=YYYY-MM-DD

Detail van één voorkomen (zonder date: het eerste). Extra velden: upcoming_dates (volgende 12 datums binnen 6 maanden) en ics_url.

Agenda-sync

  • GET /places/{slug}/events.ics — abonneerbare iCal-feed (alle events, met RRULE's). In de app: "Abonneer op agenda" → open webcal://gemeente.leet.onl/api/v1/places/uden/events.ics.
  • GET /places/{slug}/events/{id}.ics — één event toevoegen.
  • GET /me/rsvps.ics (met token) — feed van je eigen aanmeldingen.
  • Native alternatief: EventKit (iOS) / CalendarContract (Android) met de velden uit het Event-object.

3.4 Verenigingen

  • GET /places/{slug}/organizations?category=&q= — gepagineerd (per_page max 100).
  • GET /places/{slug}/organizations/{slug|id} — Organization + upcoming_events (3 maanden), volunteering, news.

Organization: id, slug, name, description, category, logo_url, image_url, address, postal_code, city, email, phone, website, socials.

3.5 Vrijwilligerswerk

  • GET /places/{slug}/volunteering?skill=&organization= — open vacatures (verlopen ends_at worden verborgen).
  • GET /places/{slug}/volunteering/{id}
{
  "id": 1, "title": "Opbouwhulp evenementen", "description": "<p>…</p>", "image_url": null,
  "skills": [ { "key": "organiseren", "label": "Organiseren" } ],
  "location": "Uden centrum", "time_commitment": "Een paar keer per jaar",
  "starts_at": null, "ends_at": null,
  "spots": 10, "spots_taken": 3,
  "contact_name": "…", "contact_email": "…",
  "organization": { "id": 1, "slug": "…", "name": "…", "logo_url": null },
  "my_signup": null      // "pending" | "accepted" | "declined" | null
}
  • GET /skills — alle vaardigheden [{key, label}] voor het profiel en filters.

3.6 Nieuws

  • GET /places/{slug}/news?category=&organization= — vastgezette eerst, dan nieuwste (per_page max 50).
  • GET /places/{slug}/news/{slug|id} — incl. body (HTML).

NewsPost: id, slug, title, excerpt, body (alleen detail), image_url, source_url, published_at, is_pinned, category, organization.

3.7 Gemeente-info

GET /places/{slug}/info — gegroepeerd:

{ "data": [
  { "section": "Gemeente", "items": [
    { "id": 1, "slug": "gemeente-maashorst", "type": "page", "title": "Gemeente Maashorst", "icon": "building.columns", "body": "<p>…</p>", "url": "https://www.gemeentemaashorst.nl", "phone": null },
    { "id": 2, "slug": "…", "type": "phone", "title": "Gemeente Maashorst bellen", "icon": "phone", "body": null, "url": null, "phone": "0413 28 19 11" }
  ]},
  { "section": "Noodnummers", "items": [ … ] }
]}

type: page → detailscherm met body; link → open url; phone → tel:-link. GET /places/{slug}/info/{slug|id} — één item.

3.8 Afvalkalender

GET /places/{slug}/waste?from=&to=&area= (standaard vandaag t/m +3 maanden):

{
  "data": [ { "id": 7, "date": "2026-11-24", "type": "gft", "label": "GFT", "color": "#2E7D32", "area": null, "note": null } ],
  "types": { "gft": {"label":"GFT","color":"#2E7D32"}, "pmd": {…}, "rest": {…}, "papier": {…}, "glas": {…}, "textiel": {…} }
}

Met area krijg je de ophaaldagen voor dat gebied plus die voor de hele plaats (area: null). Tip: plan lokaal een melding de avond ervoor.


4. Account (inloggen is optioneel)

Bladeren werkt zonder account. Een account is nodig voor aanmelden bij events, vrijwilligerswerk en het profiel.

POST /auth/register
{"name":"Jan","email":"jan@example.com","password":"minimaal8","place":"uden","device_name":"iPhone van Jan"}
→ 201 {"token":"12|abc…","token_type":"Bearer","user":{User}}

POST /auth/login
{"email":"jan@example.com","password":"…","device_name":"Pixel 8"}
→ 200 {"token":"…","token_type":"Bearer","user":{User}}

Bewaar het token in de Keychain (iOS) / EncryptedSharedPreferences/DataStore (Android) en stuur mee als Authorization: Bearer 12|abc…. Tokens verlopen niet; bij 401 → uitloggen en naar loginscherm.

User-object:

{
  "id": 2, "name": "Jan", "email": "jan@example.com", "phone": "0612345678", "avatar_url": null,
  "home_place": "uden",
  "skills": [ { "key": "bar", "label": "Bar & horeca" } ],
  "notification_settings": {},
  "stats": { "events_attended": 3, "volunteer_signups": 2, "volunteer_accepted": 1 },
  "created_at": "2026-11-19T00:59:02+01:00"
}

stats is bedoeld voor een "jouw impact"-blok / badges in het profiel.

Methode Endpoint Body / omschrijving
GET /me Profiel
PUT /me {name?, phone?, skills?: ["bar","techniek"], notification_settings?: {…}, place?: "uden", password?}
DELETE /me Account + alle gegevens verwijderen (verplicht in de app voor App Store)
POST /auth/logout Huidig token intrekken
POST /events/{id}/rsvp {"date":"2027-01-12","status":"going"} (going/interested; date weglaten = eerste voorkomen) → 201/200 met het bijgewerkte Event. 422 als vol of als het event niet op die datum valt.
DELETE /events/{id}/rsvp?date=YYYY-MM-DD Afmelden → 204
GET /me/rsvps Mijn komende aanmeldingen als Event-lijst
POST /volunteering/{id}/signup {"message":"…"} → {"data":{"id":5,"status":"pending"}}. 422 als alle plekken bezet zijn.
DELETE /volunteering/{id}/signup Intrekken → 204
GET /me/volunteering [{id, status, message, created_at, opportunity: Volunteer}]

De beheerder ziet aanmeldingen in het beheer en kan vrijwilligers accepteren/afwijzen; de status komt terug in my_signup.


5. Pushmeldingen

  1. App vraagt toestemming en haalt een FCM-token op (Firebase Messaging; op iOS gekoppeld aan APNs in de Firebase-console).
  2. Registreer (met of zonder login — met login wordt het toestel aan de gebruiker gekoppeld):
POST /devices
{"place":"uden","platform":"ios","token":"<fcm-token>","topics":["news","events","waste","volunteering"],"app_version":"1.0.0","locale":"nl"}

Opnieuw aanroepen bij elke app-start of token-refresh is prima (upsert op token). topics: null = alles.

  1. Afmelden: DELETE /devices {"token":"…"}.

Beheerders versturen berichten via Beheer → App → Pushberichten. Payload:

{
  "notification": { "title": "Uden On Ice opent vandaag!", "body": "…" },
  "data": { "place": "uden", "link_type": "event", "link_id": "2" }
}

link_type: event (id) · news (slug/id) · business (slug/id) · url (volledige URL) → open het juiste scherm (deep link).

Server-configuratie: FCM_PROJECT_ID en FCM_CREDENTIALS (pad naar service-account JSON) in .env.


6. Aanbevolen app-opbouw

Scherm Endpoint(s)
Opstarten GET /places/{slug} (kleuren, modules, settings) → cache
Home GET /places/{slug}/home
Agenda (lijst/kalender) GET /events?from&to per maand; filters via /categories?type=event
Event-detail GET /events/{id}?date= · RSVP · events/{id}.ics
Bedrijvengids /categories?type=business → /businesses?category= · kaartweergave via location
Bedrijf-detail /businesses/{slug} (bellen, mailen, route, website, openingstijden)
Verenigingen /organizations → detail
Vrijwilligers /volunteering?skill= → detail → signup
Nieuws /news → detail
Info / gemeente /info + /waste
Zoeken /search?q=
Profiel /me, /me/rsvps, /me/volunteering, /skills, account verwijderen

Tab-balk (max 5): Home · Agenda · Gids · Vrijwilligers · Meer (Meer = verenigingen, nieuws, info, afval, profiel). Verberg tabs van uitgeschakelde modules.


7. Data vullen: MCP-server

De MCP-server is bedoeld om alle inhoud te laten vullen door Claude (bijvoorbeeld na het scrapen van websites, Facebook-pagina's of agenda's).

Koppelen

  1. Beheer → API → Nieuwe API-sleutel.
  2. Je krijgt twee waarden: de Bearer-sleutel en een connector-URL https://gemeente.leet.onl/mcp/<sleutel>.
  3. In Claude: Instellingen → Connectors → Eigen connector toevoegen → plak de connector-URL. (Clients die headers ondersteunen: https://gemeente.leet.onl/mcp met Authorization: Bearer <sleutel>.)

De sleutel heeft de rechten van jouw account (alle plaatsen waar je beheerder bent). Intrekken kan op dezelfde pagina.

Tools

Tool Doet
list_places Plaatsen die je beheert, met modules en aantallen per type
save_place Nieuwe plaats/wijk aanmaken (superadmin) of instellingen/modules/kleuren wijzigen
describe_types Alle velden per type met uitleg
list_items Items van een type opzoeken (q), compacte lijst
get_item Eén item volledig
save_item Eén item aanmaken/bijwerken (id of match_on)
bulk_save Tot 200 items in één keer upserten via match_on; foute items blokkeren de rest niet
delete_item Definitief verwijderen
import_image Afbeelding van URL naar eigen opslag → path voor image_path/logo_path

Typen: businesses, events, news, organizations, volunteering, info, waste, categories.

Handig bij scrapen

  • match_on voorkomt dubbelingen bij opnieuw scrapen: bedrijven ["name"], events ["title","starts_at"], nieuws ["source_url"], afval ["waste_type","date","area"].
  • category en organization mogen als naam worden meegegeven; die worden automatisch aangemaakt.
  • Herhalende activiteiten als één event met recurrence (bv. monthly_nth_weekday met starts_at op de 2e dinsdag).
  • Zet bij nieuws altijd source_url.

Voorbeeldprompt: "Scrape de agenda van theatermarkant.nl en zet alle voorstellingen tot eind maart als events in plaats uden (categorie Cultuur, organisatie Theater Markant, met poster via import_image)."


8. Beheer-API (REST, voor eigen scrapers/scripts)

Zelfde sleutel als MCP, als Authorization: Bearer 12|abc….

Methode Endpoint
GET /manage/types — velden per type
GET /manage/places/{slug}/{type}?q=&per_page=
POST /manage/places/{slug}/{type} — aanmaken
POST /manage/places/{slug}/{type}/upsert — {"match_on":["name"], …velden}
POST /manage/places/{slug}/{type}/bulk — {"match_on":[…], "items":[…]} (max 200) → {created, updated, failed, errors, ids}
GET / PUT / PATCH / DELETE /manage/places/{slug}/{type}/{id}
POST /manage/places/{slug}/upload — multipart file → {path, url}
POST /manage/places/{slug}/import-image — {"url":"https://…"} → {path, url}
curl -X POST https://gemeente.leet.onl/api/v1/manage/places/uden/events/bulk \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"match_on":["title","starts_at"],"items":[
        {"title":"Kerstconcert","starts_at":"2026-12-20 20:00","organization":"Harmonie Uden","category":"Muziek","price":"€ 10"}
      ]}'

Herhaling (recurrence)

none · daily · weekly · biweekly · monthly_day (zelfde datum) · monthly_nth_weekday (bv. elke 2e dinsdag, afgeleid van starts_at). Optioneel recurrence_until en excluded_dates[].