Keywords and Markers

Every TRCItem carries two free-form tag fields — keywords and markers — alongside the structured Categorization. Both are comma-separated strings of short text labels, but they serve very different purposes.

Both fields exist on every entity type (events, locations, venues, routes, event groups). Both have dictionary endpoints that expose the allowed values for an account.

Keywords

Keywords are customer-facing tags — descriptive labels that an end-user might see next to the event on a partner website or in an app. They are used to:

• Group thematically related events under a campaign tag (e.g. amsterdamdanceevent for ADE-affiliated events).
• Mark short-form themes that don't fit the structured Type/Category ontology (e.g. kindvriendelijk, gratis, outdoor).
• Power free-text faceting and search filters on partner sites.

Keywords are free-form: an account can use any string. The dictionary endpoints surface the set of keywords actually in use for that account's entity, so partner UIs can offer a typeahead or a curated facet list.

Keyword endpoints

Each endpoint also has an account-scoped variant: GET /api/dictionary/{accountid}/event_keywords (and the equivalents). Use the path-parameter form when reading values for a specific account; the unscoped form uses your own account by default.

The response shape:

{
  "lastModified": "2026-04-12T08:30:00.000Z",
  "results": [
    {
      "name": "amsterdamdanceevent",
      "translations": [
        { "lang": "nl", "text": "amsterdamdanceevent" },
        { "lang": "en-GB", "text": "amsterdamdanceevent" },
        { "lang": "de", "text": "amsterdamdanceevent" }
      ]
    },
    {
      "name": "kindvriendelijk",
      "translations": [
        { "lang": "nl", "text": "kindvriendelijk" },
        { "lang": "en-GB", "text": "child-friendly" },
        { "lang": "de", "text": "kinderfreundlich" }
      ]
    }
  ]
}

Each result has a name (the literal value as it appears in trcItem.keywords) and a translations array with the value rendered into each of the API's translation languages (nl, en-GB, de, fr, no). Hashtag-style keywords usually translate to themselves; descriptive Dutch keywords get translated through the API's translation service and cached.

Where keywords come from

If the account has a curated list under account.eventKeywords (or the equivalent per-entity field), that list is returned verbatim. Otherwise, the endpoint scans the live data: it aggregates the keywords field across all approved/archived items for the account's userorganisation in the last year, and returns the unique values.

This means: add a new keyword to a few items and it becomes discoverable through the dictionary endpoint within hours — no admin action required.

Markers

Markers are technical / internal classification flags that drive routing, publication, ingestion, and integration behavior. Where keywords are descriptive, markers are imperative — they tell systems what to do with the item.

Common marker patterns:

Markers tend to be namespaced with :. The colon convention is meaningful: the dictionary endpoints treat any marker containing : as a "special marker" and surface it separately so it shows up in admin UIs even when it isn't part of the account's curated list.

Marker endpoints

Each endpoint also has an account-scoped variant: GET /api/dictionary/{accountid}/event_markers (and the equivalents).

The response shape matches keywords ({ lastModified, results: [{ name, translations }] }). The marker list is the union of:

• The account's curated list (account.eventMarkers, etc.) if present, or the live aggregation from indexed items if not.
• Special markers — any marker containing a : that appears on at least one approved item for the account's userorganisation. These are added on top of the curated list so internal routing flags remain discoverable even if an admin forgot to add them explicitly.

Markers vs Keywords: when to use which

• Will an end-user see this label on a public site? → Keyword.
• Does this label tell a system to do something (publish, route, suppress, attribute to a partner)? → Marker.
• Is the value namespaced with : (feed:, toonop:, partner:)? → Marker.
• Is the value short and tag-like, suitable as a hashtag? → Keyword.

Some accounts use both: a tourism event might carry keywords: "amsterdamdanceevent,muziekfestival" for end-user-facing tags and markers: "feed:adeofficial,toonopiamsterdam,ondertogo" for the publication pipeline.

Field shape on TRCItem

Both keywords and markers live on TRCItem as comma-separated strings, not arrays:

{
  "keywords": "amsterdamdanceevent,muziekfestival,kindvriendelijk",
  "markers": "feed:adeofficial,toonopiamsterdam,ondertogo"
}

When writing, supply a comma-separated string. When reading, split on , and trim. Empty strings are valid (no tags); null is also acceptable.

Cross-userorganisation reads

Like the Categorization ontologies, keyword and marker dictionaries are bound to the owning account. If you read items belonging to another userorganisation and want to look up which keywords/markers that organisation curates, call the path-parameter form of the endpoint with the owning account's id:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://app.eventconnectors.nl/api/dictionary/OWNING_ACCOUNT_ID/event_keywords

The owning account's id can be resolved from the item's userorganisation via GET /api/dictionary/userorganisations.

Related concepts

• Categorization — structured Types and Categories backed by ontologies, complementing free-form keywords/markers.
• TRCItem — the container holding keywords and markers.

See the API Reference for the full set of dictionary endpoints.