GraphQL Schema Reference

Overview

This page provides comprehensive documentation for the Events Content Calendar API GraphQL schema. It covers all types, queries, inputs, and enums available in the API.

Interactive Exploration

Use the GraphQL Playground in your development environment to explore the schema interactively with autocomplete and documentation.

Root Query Type

Query

The root query type provides access to all data retrieval operations.

type Query {
  events(
    criteria: searchCriteria
    index: String
    page: Int
    size: Int
    sort: SortType
  ): Events

  getEventById(id: Int, index: String): Event

  getRaceById(id: Int): Race
}

events

Retrieve a paginated list of events with optional filtering, sorting, and pagination.

Arguments:

Argument	Type	Required	Default	Description
`criteria`	searchCriteria	No	-	Filter criteria for events
`index`	String	No	-	Index name (internal use)
`page`	Int	No	0	Zero-indexed page number
`size`	Int	No	20	Items per page
`sort`	SortType	No	default	Sorting strategy

Returns: Events - Paginated events response with data, facets, and pagination info.

Example:

query {
  events(
    criteria: { countries: ["US"], sports: [run] }
    page: 0
    size: 20
    sort: date_asc
  ) {
    totalCount
    data {
      id
      name { en }
    }
  }
}

getEventById

Retrieve a single event by its unique identifier.

Arguments:

Argument	Type	Required	Description
`id`	Int	Yes	Event ID
`index`	String	No	Index name (internal use)

Returns: Event - Single event object or null if not found.

Example:

query {
  getEventById(id: 12345) {
    id
    name { en }
    location { en }
  }
}

getRaceById

Retrieve a single race by its unique identifier.

Arguments:

Argument	Type	Required	Description
`id`	Int	Yes	Race ID

Returns: Race - Single race object or null if not found.

Example:

query {
  getRaceById(id: 67890) {
    id
    raceName
    distanceKm
  }
}

Core Types

Event

Represents a sports event with collapsed edition data.

type Event {
  id: Int
  name: LocalizedString
  permalink: String
  nameLanguage: String

  # Location
  city: LocalizedString
  location: LocalizedString
  country: LocalizedCountry
  countryIso: String
  lonlat: [Float!]
  region1: eventRegion1
  region2: eventRegion2

  # Sport & Classification
  sport: eventSport
  eventStatus: eventStatus

  # Current Edition
  editionId: Int
  editionStatus: editionStatus
  startDate: String

  # Description
  description: LocalizedDescription

  # URLs & Registration
  eventPageUrl: String
  localizedEventPageUrl: LocalizedString
  checkoutUrl: String
  isRegistrationOpen: Boolean

  # [Partner Name] Integration
  [partnerName]Relationship: [PartnerName]RelationshipEnum
  [partnerName]Image: String

  # Ahotu Features
  isAhotuEvent: Boolean

  # Races
  races: [Race!]
  distancesInKm: [Float!]

  # Metadata
  updatedAt: String
}

Key Fields:

Field	Type	Description
`id`	Int	Unique event identifier
`name`	LocalizedString	Event name in multiple languages
`city`	LocalizedString	City name localized
`country`	LocalizedCountry	Country with ISO code and names
`countryIso`	String	ISO 3166-1 alpha-2 code (e.g., "US")
`lonlat`	[Float!]	[longitude, latitude] coordinates
`sport`	eventSport	Primary sport classification
`startDate`	String	ISO 8601 date (YYYY-MM-DD)
`races`	[Race!]	List of races within this event
`editionStatus`	editionStatus	Current edition status
`isRegistrationOpen`	Boolean	Registration currently available
`checkoutUrl`	String	Direct registration URL

Events

Paginated events response with facets and metadata.

type Events {
  data: [Event!]
  totalCount: Int
  pageCount: Int
  pageInfo: PageInfo
  facets: Facets
}

Fields:

Field	Type	Description
`data`	[Event!]	Array of event objects
`totalCount`	Int	Total number of matching events
`pageCount`	Int	Total number of pages
`pageInfo`	PageInfo	Pagination navigation info
`facets`	Facets	Aggregated filter counts

Race

Represents a specific race distance/category within an event.

type Race {
  id: Int
  raceName: String

  # Distance
  distanceKm: Float
  distanceType: distanceType

  # Timing
  startDate: String
  startTime: String
  minutes: Float

  # Sport & Participation
  sport: sport
  participant: participation

  # Team Info
  minNumberOfTeamMembers: Int
  maxNumberOfTeamMembers: Int

  # Activities & Tags
  activities: [Activity!]
  tags: [tags!]

  # Location
  continent: Int
}

Key Fields:

Field	Type	Description
`id`	Int	Unique race identifier
`raceName`	String	Name of the race (e.g., "Full Marathon")
`distanceKm`	Float	Distance in kilometers
`distanceType`	distanceType	Standard distance category
`startDate`	String	Race start date (YYYY-MM-DD)
`startTime`	String	Race start time (HH:MM)
`participant`	participation	Solo, relay, or team
`activities`	[Activity!]	List of activities (for multi-sport)

Activity

Represents a single activity/discipline within a race (primarily for multi-sport events).

type Activity {
  # Distance
  distance: Float
  distanceKm: Float
  distanceUnit: distanceUnit

  # Elevation
  elevationGain: Float
  elevationGainUnit: elevationGainUnit
  elevationDrop: Float
  elevationDropUnit: elevationDropUnit

  # Course Characteristics
  courseProfile: courseProfile
  courseType: courseType
  courseLoopDistance: Float
  courseLoopDistanceUnit: courseLoopDistanceUnit
  courseLoopElevationGain: Float
  courseLoopElevationGainUnit: courseLoopElevationGainUnit

  # Tags
  terrain: [terrain!]
  environment: [environments!]
  others: [others!]

  # Order
  order: Int
}

Key Fields:

Field	Type	Description
`distance`	Float	Activity distance (original unit)
`distanceKm`	Float	Distance normalized to kilometers
`elevationGain`	Float	Total elevation gain
`courseProfile`	courseProfile	Terrain difficulty (flat/hilly/extreme)
`courseType`	courseType	Course layout (loop/out-and-back/etc)
`terrain`	[terrain!]	Surface types (road/trail/etc)
`environment`	[environments!]	Environmental tags (scenic/mountain/etc)
`order`	Int	Activity sequence number

Localization Types

LocalizedString

String values available in all supported languages.

type LocalizedString {
  en: String        # English
  en_US: String     # English (United States)
  en_GB: String     # English (United Kingdom)
  es: String        # Spanish
  es_419: String    # Spanish (Latin America)
  fr: String        # French
  de: String        # German
  it: String        # Italian
  pt: String        # Portuguese
  pt_BR: String     # Portuguese (Brazilian)
  nl: String        # Dutch
  sv: String        # Swedish
  ru: String        # Russian
  ja: String        # Japanese
  ko: String        # Korean
  zh: String        # Chinese
  zh_HANT: String   # Chinese (Traditional)
  th: String        # Thai
  tr: String        # Turkish
  id: String        # Indonesian
}

Usage:

query {
  events(page: 0, size: 10) {
    data {
      name {
        en
        es
        fr
      }
    }
  }
}

LocalizedDescription

Event descriptions with AI generation flag.

type LocalizedDescription {
  en: Description
  en_US: Description
  en_GB: Description
  es: Description
  es_419: Description
  fr: Description
  de: Description
  it: Description
  pt: Description
  pt_BR: Description
  nl: Description
  sv: Description
  ru: Description
  ja: Description
  ko: Description
  zh: Description
  zh_HANT: Description
  th: Description
  tr: Description
  id: Description
}

type Description {
  text: String
  isAiGenerated: Boolean
}

Usage:

query {
  getEventById(id: 12345) {
    description {
      en {
        text
        isAiGenerated
      }
    }
  }
}

LocalizedCountry

Country information with ISO code and localized names.

type LocalizedCountry {
  isoCode: String
  names: LocalizedString
}

Example:

{
  "isoCode": "FR",
  "names": {
    "en": "France",
    "es": "Francia",
    "de": "Frankreich"
  }
}

Pagination Types

PageInfo

Pagination navigation metadata.

type PageInfo {
  currentPage: Int
  startPage: Int
  endPage: Int
  hasNextPage: Boolean
  hasPreviousPage: Boolean
}

Fields:

Field	Description
`currentPage`	Current page number (zero-indexed)
`startPage`	First page number (always 0)
`endPage`	Last page number
`hasNextPage`	True if more pages available
`hasPreviousPage`	True if previous pages exist

Aggregated filter counts for faceted navigation.

type Facets {
  sport: [FacetValue!]
  country: [FacetValue!]
  cities: [FacetValue!]
  months: [FacetValue!]
  distance: [FacetValue!]
  courseProfile: [FacetValue!]
  courseType: [FacetValue!]
  terrain: [FacetValue!]
  environments: [FacetValue!]
  participation: [FacetValue!]
  raceFormat: [FacetValue!]
  raceType: [FacetValue!]
  qualifiers: [FacetValue!]
  restriction: [FacetValue!]
  others: [FacetValue!]
  technique: [FacetValue!]
}

type FacetValue {
  key: String
  count: Int
}

Usage:

query {
  events(criteria: { countries: ["US"] }) {
    facets {
      sport {
        key    # e.g., "run"
        count  # e.g., 8923
      }
      distance {
        key    # e.g., "marathon"
        count  # e.g., 234
      }
    }
  }
}

Input Types

searchCriteria

Filter criteria for event queries.

input searchCriteria {
  # Location Filters
  countries: [String!]
  regions1: [Region1Enum!]
  regions2: [Region2Enum!]
  city: String
  around: Around

  # Sport Filters
  sports: [SportEnum!]

  # Date Filters
  dateRange: DateRange

  # Distance Filters
  distanceRange: DistanceRange
  distanceTypes: [DistanceTypeEnum!]

  # Course Filters
  courseProfiles: [CourseProfileEnum!]
  courseTypes: [CourseTypeEnum!]
  terrains: [TerrainEnum!]

  # Tag Filters
  environments: [EnvironmentEnum!]
  participations: [ParticipationEnum!]
  others: [OtherEnum!]

  # Status Filters
  eventStatus: EventStatusEnum
  editionStatus: EditionStatusEnum

  # Text Search
  text: String
}

Around

Geo-spatial radius filter.

input Around {
  point: Point!
  distance: String  # e.g., "50km", "25mi"
}

input Point {
  lat: Float!
  lon: Float!
}

Usage:

query {
  events(
    criteria: {
      around: {
        point: { lat: 40.7128, lon: -74.0060 }
        distance: "50km"
      }
    }
  ) {
    data {
      name { en }
    }
  }
}

DateRange

Date range filter for event start dates.

input DateRange {
  dateFrom: String  # YYYY-MM-DD
  dateTo: String    # YYYY-MM-DD
}

Usage:

query {
  events(
    criteria: {
      dateRange: {
        dateFrom: "2024-06-01"
        dateTo: "2024-08-31"
      }
    }
  ) {
    data {
      name { en }
      startDate
    }
  }
}

DistanceRange

Distance range filter for races.

input DistanceRange {
  min: Float
  max: Float
  unit: Unit
}

Usage:

query {
  events(
    criteria: {
      distanceRange: {
        min: 21.0
        max: 42.2
        unit: km
      }
    }
  ) {
    data {
      name { en }
      distancesInKm
    }
  }
}

Enum Types

SortType

Sorting strategies for event queries.

enum SortType {
  default        # Relevance-based
  date_asc       # Earliest first
  date_desc      # Latest first
  distance_asc   # Shortest first
  distance_desc  # Longest first
  geopoint_asc   # Nearest first (requires around filter)
  geopoint_desc  # Farthest first (requires around filter)
}

SportEnum

Available sport types.

enum SportEnum {
  run
  trail_run
}

note

Sport availability depends on tenant configuration. Additional sports may be available.

DistanceTypeEnum

Standard distance classifications.

enum DistanceTypeEnum {
  _5k
  _10k
  half_marathon
  marathon
  other
}

CourseProfileEnum

Terrain difficulty levels.

enum CourseProfileEnum {
  flat
  undulating
  hilly
  extreme
}

Descriptions:

flat - Minimal elevation change, fast courses
undulating - Rolling hills, moderate difficulty
hilly - Significant elevation, challenging
extreme - Very difficult terrain, major elevation

CourseTypeEnum

Course layout patterns.

enum CourseTypeEnum {
  point_to_point
  out_and_back
  single_loop
  loops
}

Descriptions:

point_to_point - Start and finish at different locations
out_and_back - Run out and return on same route
single_loop - One continuous circuit
loops - Multiple laps of the same course

TerrainEnum

Surface types for races.

enum TerrainEnum {
  road
  trail
  track
  indoor
  multi_terrain
  gravel
  snow
  sand
  urban_trail
  bay
  canal
  lake
  river
  sea
  pool
  dirt_road
  stationary
  treadmill
}

EnvironmentEnum

Environmental and atmospheric tags.

enum EnvironmentEnum {
  # Scenery
  scenic
  nature
  mountain
  beach
  forest
  countryside
  valley
  vineyards

  # Water Features
  lakeside
  seaside
  ocean_view
  river
  waterfalls

  # Urban/Man-Made
  city
  capital_city
  historical
  castle
  bridge
  tunnel

  # Special Locations
  unesco_world_heritage
  amusement_park
  zoo
  stadium
  airport
  motor_speedway

  # Event Type
  night
  sunset
  music
  color_run

  # Terrain Specific
  glacier
  polar
  desert
  island

  # Other
  closed_road
  residential
  park
  sport_club
  indoor
}

ParticipationEnum

Participation formats.

enum ParticipationEnum {
  solo
  relay
  team
}

OtherEnum

Additional event characteristics.

enum OtherEnum {
  beginner_friendly
  family_friendly
  wheelchair_friendly
  fun
  timed
  course_certified
  eco_friendly
  ebike_allowed
  ebike_only
  beer
  wine
  halloween
  flippers
  wildlife
}

EventStatusEnum

Event-level status.

enum EventStatusEnum {
  ok
  archived
  deleted
  duplicate
  incomplete
  incorrect
  terminated
  to_be_validated
}

EditionStatusEnum

Edition-specific status.

enum EditionStatusEnum {
  ok
  canceled
  postponed
  turned_virtual
  no_race
  deleted
}

Descriptions:

ok - Event is happening as scheduled
canceled - Event has been canceled
postponed - Event date has been rescheduled
turned_virtual - Event moved to virtual/remote format
no_race - No edition this year
deleted - Edition removed from catalog

[PartnerName]RelationshipEnum

[Partner name] affiliation status.

enum [PartnerName]RelationshipEnum {
  NO_RELATIONSHIP
  [PARTNERNAME]_SPONSORED
  [PARTNERNAME]_OWNED
}

Unit

Measurement units.

enum Unit {
  km
  m
  mi
  ft
  yard
  step
}

Reference Types

These types provide localized names and codes for various attributes.

Common Pattern

Most reference types follow this pattern:

type <AttributeType> {
  code: String
  names: LocalizedString
}

Example:

{
  "code": "run",
  "names": {
    "en": "Running",
    "es": "Correr",
    "fr": "Course à pied"
  }
}

Available Reference Types

sport - Sport classifications
distanceType - Distance categories
distanceUnit - Distance measurement units
courseProfile - Terrain difficulty
courseType - Course layouts
terrain - Surface types
environments - Environmental tags
others - Additional attributes
participation - Participation formats
eventStatus - Event status
editionStatus - Edition status
eventRegion1 - Primary regions
eventRegion2 - Secondary regions
tags - General tags

Region Enums

Region1Enum

Primary administrative regions (states, provinces, etc.). See schema for complete list.

Examples:

california
new_york
texas
ontario
quebec
bavaria
ile_de_france

Region2Enum

Secondary administrative regions (counties, departments, etc.). See schema for complete list.

Best Practices

1. Request Only Needed Fields

# Good - Specific fields
query {
  events(page: 0, size: 10) {
    data {
      id
      name { en }
      startDate
    }
  }
}

2. Use Fragments for Reusability

fragment EventBasics on Event {
  id
  name { en }
  startDate
  city { en }
}

query {
  events(page: 0, size: 10) {
    data {
      ...EventBasics
    }
  }
}

3. Leverage Variables

query GetEvents($country: [String!], $page: Int!, $size: Int!) {
  events(
    criteria: { countries: $country }
    page: $page
    size: $size
  ) {
    data {
      name { en }
    }
  }
}

Variables:

{
  "country": ["US"],
  "page": 0,
  "size": 20
}

4. Handle Null Values

All fields can potentially be null. Always check for null in your application logic.

const eventName = event.name?.en || 'Unknown Event';
const distance = race.distanceKm || 0;

5. Use Aliases for Multiple Queries

query {
  usEvents: events(criteria: { countries: ["US"] }, page: 0, size: 10) {
    totalCount
  }

  frenchEvents: events(criteria: { countries: ["FR"] }, page: 0, size: 10) {
    totalCount
  }
}

Schema Introspection

Get Schema Information

Query the schema itself using GraphQL introspection:

query {
  __schema {
    types {
      name
      kind
    }
  }
}

Get Type Details

query {
  __type(name: "Event") {
    name
    fields {
      name
      type {
        name
      }
    }
  }
}

Next Steps

🎮 Try queries in the GraphQL Playground
📝 Review Query Examples for practical use cases
🏗️ Understand the Data Model architecture
🔐 Check Authentication for API access

Overview​

Root Query Type​

Query​

events​

getEventById​

getRaceById​

Core Types​

Event​

Events​

Race​

Activity​

Localization Types​

LocalizedString​

LocalizedDescription​

LocalizedCountry​

Pagination Types​

PageInfo​

Facets Types​

Facets​

Input Types​

searchCriteria​

Around​

DateRange​

DistanceRange​

Enum Types​

SortType​

SportEnum​

DistanceTypeEnum​

CourseProfileEnum​

CourseTypeEnum​

TerrainEnum​

EnvironmentEnum​

ParticipationEnum​

OtherEnum​

EventStatusEnum​

EditionStatusEnum​

[PartnerName]RelationshipEnum​

Unit​

Reference Types​

Common Pattern​

Available Reference Types​

Region Enums​

Region1Enum​

Region2Enum​

Best Practices​

1. Request Only Needed Fields​

2. Use Fragments for Reusability​

3. Leverage Variables​

4. Handle Null Values​

5. Use Aliases for Multiple Queries​

Schema Introspection​

Get Schema Information​

Get Type Details​

Next Steps​

Overview

Root Query Type

Query

events

getEventById

getRaceById

Core Types

Event

Events

Race

Activity

Localization Types

LocalizedString

LocalizedDescription

LocalizedCountry

Pagination Types

PageInfo

Facets Types

Facets

Input Types

searchCriteria

Around

DateRange

DistanceRange

Enum Types

SortType

SportEnum

DistanceTypeEnum

CourseProfileEnum

CourseTypeEnum

TerrainEnum

EnvironmentEnum

ParticipationEnum

OtherEnum

EventStatusEnum

EditionStatusEnum

[PartnerName]RelationshipEnum

Unit

Reference Types

Common Pattern

Available Reference Types

Region Enums

Region1Enum

Region2Enum

Best Practices

1. Request Only Needed Fields

2. Use Fragments for Reusability

3. Leverage Variables

4. Handle Null Values

5. Use Aliases for Multiple Queries

Schema Introspection

Get Schema Information

Get Type Details

Next Steps