Skip to main content

Query Examples

Overview​

This guide provides practical GraphQL query examples for common use cases. All examples assume you have a valid OAuth2 access token.

Quick Start

Copy these examples directly into the GraphQL Playground to test them. Replace filter values with your specific needs.

Basic Queries​

Get Recent Events​

Retrieve the most recent events with basic information.

query {
  events(page: 1, size: 10, sort: date_desc) {
    totalCount
    data {
      id
      name { en }
      startDate
      city { en }
      country {
        isoCode
        names { en }
      }
    }
  }
}

Use Case: Display upcoming events on a homepage or dashboard.

Get Event by ID​

Retrieve detailed information about a specific event.

query {
  getEventById(id: 12345) {
    id
    name { en }
    description { en { text } }
    startDate
    location { en }
    city { en }
    country {
      isoCode
      names { en }
    }
    lonlat
    eventPageUrl
    checkoutUrl
    isRegistrationOpen
    races {
      id
      raceName
      distanceKm
      startDate
      startTime
    }
  }
}

Use Case: Event detail page showing all information about a specific event.

Get Race by ID​

Retrieve detailed information about a specific race.

query {
  getRaceById(id: 67890) {
    id
    raceName
    distanceKm
    distanceType {
      code
      names { en }
    }
    startDate
    startTime
    sport {
      code
      names { en }
    }
    ticketsSummary {
        currency
        minPrice
        maxPrice
    }
    activities {
      distance
      distanceKm
      distanceUnit {
        code
        names { en }
      }
      elevationGain
      elevationGainUnit {
        code
        names { en }
      }
      courseProfile {
        code
        names { en }
      }
      terrain {
        code
        names { en }
      }
    }
  }
}

Use Case: Race detail view with all technical specifications.

Location-Based Queries​

Find Events Near a Location​

Find events within a specific radius of geographic coordinates.

query {
  events(
    criteria: {
      around: {
        point: { lat: 40.7128, lon: -74.0060 }
        distance: "50km"
      }
    }
    sort: geopoint_asc
    page: 0
    size: 20
  ) {
    totalCount
    data {
      id
      name { en }
      startDate
      city { en }
      lonlat
      distancesInKm
    }
  }
}

Use Case: "Events near me" feature using user's current location.

tip

The distance parameter in the around filter accepts values like "50km", "25mi", "100km".

Events in Specific Countries​

Filter events by one or more countries using ISO codes.

query {
  events(
    criteria: {
      countries: ["US", "CA", "MX"]
    }
    page: 0
    size: 50
  ) {
    totalCount
    data {
      id
      name { en }
      startDate
      city { en }
      countryIso
    }
  }
}

Use Case: Regional event listings for North America.

Events in a Specific City​

Search for events in a particular city.

query {
  events(
    criteria: {
      city: "Berlin"
    }
    page: 0
    size: 20
  ) {
    totalCount
    data {
      id
      name { en }
      startDate
      location { en }
    }
  }
}

Use Case: City-specific event calendar.

Sport & Distance Filters​

Filter by Sport​

Find events for specific sports.

query {
  events(
    criteria: {
      sports: [run, trail_run]
    }
    page: 0
    size: 30
  ) {
    totalCount
    data {
      id
      name { en }
      sport {
        code
        names { en }
      }
      startDate
      distancesInKm
    }
  }
}

Use Case: Sport-specific event listings (e.g., "All Running Events").

Filter by Standard Distance​

Find events with specific standard distances.

query {
  events(
    criteria: {
      distanceTypes: [marathon, half_marathon]
    }
    page: 0
    size: 20
  ) {
    totalCount
    data {
      id
      name { en }
      startDate
      races {
        raceName
        distanceKm
        distanceType {
          code
          names { en }
        }
      }
    }
  }
}

Use Case: Marathon/Half-Marathon finder.

Filter by Distance Range​

Find events within a specific distance range.

query {
  events(
    criteria: {
      distanceRange: {
        min: 5.0
        max: 15.0
        unit: km
      }
    }
    page: 0
    size: 20
  ) {
    totalCount
    data {
      id
      name { en }
      distancesInKm
      races {
        raceName
        distanceKm
      }
    }
  }
}

Use Case: "Beginner-friendly" races between 5-15km.

note

Available units: km, mi, m, ft, yard, step

Date-Based Queries​

Events in Date Range​

Find events occurring within a specific date range.

query {
  events(
    criteria: {
      dateRange: {
        dateFrom: "2024-06-01"
        dateTo: "2024-08-31"
      }
    }
    sort: date_asc
    page: 0
    size: 50
  ) {
    totalCount
    data {
      id
      name { en }
      startDate
      city { en }
    }
  }
}

Use Case: Summer events calendar.

Upcoming Events​

Find events starting from today onwards.

query {
  events(
    criteria: {
      dateRange: {
        dateFrom: "2024-10-07"
      }
    }
    sort: date_asc
    page: 0
    size: 20
  ) {
    totalCount
    data {
      id
      name { en }
      startDate
      city { en }
      countryIso
    }
  }
}

Use Case: "Upcoming Events" list.

Dynamic Dates

In your application, use the current date dynamically for the dateFrom parameter.

Course Characteristics​

Filter by Terrain​

Find events based on terrain type.

query {
  events(
    criteria: {
      terrains: [trail, mountain]
    }
    page: 0
    size: 20
  ) {
    totalCount
    data {
      id
      name { en }
      races {
        raceName
        distanceKm
        activities {
          terrain {
            code
            names { en }
          }
        }
      }
    }
  }
}

Use Case: Trail running event finder.

Filter by Course Profile​

Find events based on elevation difficulty.

query {
  events(
    criteria: {
      courseProfiles: [flat, undulating]
    }
    page: 0
    size: 20
  ) {
    totalCount
    data {
      id
      name { en }
      races {
        raceName
        activities {
          courseProfile {
            code
            names { en }
          }
          elevationGain
        }
      }
    }
  }
}

Use Case: "Flat and fast" race finder for PR attempts.

Filter by Environment Tags​

Find events with specific environmental features.

query {
  events(
    criteria: {
      environments: [scenic, mountain, nature]
    }
    page: 0
    size: 20
  ) {
    totalCount
    data {
      id
      name { en }
      startDate
      races {
        raceName
        activities {
          environment {
            code
            names { en }
          }
        }
      }
    }
  }
}

Use Case: Scenic/destination race recommendations.

Combined Filters​

Complex Multi-Filter Query​

Combine multiple criteria for precise results.

query {
  events(
    criteria: {
      countries: ["FR", "IT", "ES"]
      sports: [run]
      distanceTypes: [marathon]
      dateRange: {
        dateFrom: "2024-09-01"
        dateTo: "2024-12-31"
      }
      courseProfiles: [flat, undulating]
      environments: [scenic, historical]
    }
    sort: date_asc
    page: 0
    size: 20
  ) {
    totalCount
    data {
      id
      name { en }
      startDate
      city { en }
      country {
        names { en }
      }
      races {
        raceName
        distanceKm
        activities {
          courseProfile {
            names { en }
          }
          environment {
            names { en }
          }
        }
      }
    }
  }
}

Use Case: "Flat, scenic fall marathons in Southern Europe" - highly targeted search.

Location + Date + Distance​

Find marathons near a location within a date range.

query {
  events(
    criteria: {
      around: {
        point: { lat: 51.5074, lon: -0.1278 }
        distance: "200km"
      }
      dateRange: {
        dateFrom: "2024-10-01"
        dateTo: "2024-12-31"
      }
      distanceTypes: [marathon, half_marathon]
    }
    sort: geopoint_asc
    page: 0
    size: 20
  ) {
    totalCount
    data {
      id
      name { en }
      startDate
      city { en }
      lonlat
      distancesInKm
    }
  }
}

Use Case: "Marathons near London this fall" search.

Get Events with Facets​

Retrieve events along with aggregated filter counts.

query {
  events(
    criteria: {
      countries: ["US"]
      dateRange: {
        dateFrom: "2024-10-01"
      }
    }
    page: 0
    size: 20
  ) {
    totalCount
    pageCount
    facets {
      sport {
        key
        count
      }
      distance {
        key
        count
      }
      courseProfile {
        key
        count
      }
      months {
        key
        count
      }
      cities {
        key
        count
      }
    }
    data {
      id
      name { en }
      startDate
    }
  }
}

Response Example:

{
  "totalCount": 1247,
  "facets": {
    "sport": [
      { "key": "run", "count": 892 },
      { "key": "trail_run", "count": 355 }
    ],
    "distance": [
      { "key": "marathon", "count": 234 },
      { "key": "half_marathon", "count": 456 },
      { "key": "_10k", "count": 312 },
      { "key": "_5k", "count": 245 }
    ],
    "courseProfile": [
      { "key": "flat", "count": 567 },
      { "key": "undulating", "count": 432 },
      { "key": "hilly", "count": 198 },
      { "key": "extreme", "count": 50 }
    ]
  }
}

Use Case: Build dynamic filter UI showing available options and counts.

Text Search​

Full-Text Search​

Search events by name, location, or description.

query {
  events(
    criteria: {
      text: "marathon"
    }
    page: 0
    size: 20
  ) {
    totalCount
    data {
      id
      name { en }
      location { en }
      startDate
    }
  }
}

Use Case: Search bar functionality.

tip

Text search is fuzzy-matched and searches across event names, locations, and descriptions.

Combined Text and Filters​

Combine text search with other filters.

query {
  events(
    criteria: {
      text: "trail"
      countries: ["US"]
      dateRange: {
        dateFrom: "2024-10-01"
        dateTo: "2024-12-31"
      }
    }
    page: 0
    size: 20
  ) {
    totalCount
    data {
      id
      name { en }
      startDate
      city { en }
    }
  }
}

Use Case: "Find trail races in the US this fall" search.

Sorting Options​

Sort by Date​

# Ascending (earliest first)
query {
  events(sort: date_asc, page: 0, size: 10) {
    data {
      name { en }
      startDate
    }
  }
}

# Descending (latest first)
query {
  events(sort: date_desc, page: 0, size: 10) {
    data {
      name { en }
      startDate
    }
  }
}

Sort by Distance​

# By race distance (ascending)
query {
  events(
    criteria: { sports: [run] }
    sort: distance_asc
    page: 0
    size: 10
  ) {
    data {
      name { en }
      distancesInKm
    }
  }
}

Sort by Geographic Proximity​

query {
  events(
    criteria: {
      around: {
        point: { lat: 40.7128, lon: -74.0060 }
        distance: "100km"
      }
    }
    sort: geopoint_asc
    page: 0
    size: 10
  ) {
    data {
      name { en }
      city { en }
      lonlat
    }
  }
}

Available Sort Types:

  • default - Relevance-based (recommended for text searches)
  • date_asc - Earliest dates first
  • date_desc - Latest dates first
  • distance_asc - Shortest distances first
  • distance_desc - Longest distances first
  • geopoint_asc - Nearest locations first (requires around criteria)
  • geopoint_desc - Farthest locations first (requires around criteria)

Pagination​

Basic Pagination​

# First page
query {
  events(page: 0, size: 20) {
    totalCount
    pageCount
    pageInfo {
      currentPage
      hasNextPage
      hasPreviousPage
    }
    data {
      id
      name { en }
    }
  }
}

# Second page
query {
  events(page: 1, size: 20) {
    data {
      id
      name { en }
    }
  }
}

Pagination with Navigation Info​

query {
  events(page: 5, size: 20) {
    totalCount
    pageCount
    pageInfo {
      currentPage
      startPage
      endPage
      hasNextPage
      hasPreviousPage
    }
    data {
      id
      name { en }
    }
  }
}

Response:

{
  "totalCount": 1247,
  "pageCount": 63,
  "pageInfo": {
    "currentPage": 5,
    "startPage": 0,
    "endPage": 62,
    "hasNextPage": true,
    "hasPreviousPage": true
  }
}

Multilingual Queries​

Request Multiple Languages​

query {
  events(page: 0, size: 10) {
    data {
      id
      name {
        en
        es
        fr
        de
        it
      }
      location {
        en
        es
      }
      city {
        en
      }
    }
  }
}

Use Case: Multi-language application support.

Detect Source Language​

query {
  events(page: 0, size: 10) {
    data {
      id
      name { en }
      nameLanguage
    }
  }
}

Use Case: Identify the original language of the event name.

Advanced Use Cases​

Events with Open Registration​

query {
  events(
    criteria: {
      dateRange: {
        dateFrom: "2024-10-07"
      }
    }
    page: 0
    size: 20
  ) {
    data {
      id
      name { en }
      startDate
      isRegistrationOpen
      checkoutUrl
    }
  }
}

Use Case: "Register now" event listings.

[Partner Name] Sponsored Events​

query {
  events(page: 0, size: 20) {
    data {
      id
      name { en }
      [partnerName]Relationship
      [partnerName]Image
      startDate
    }
  }
}

Filter in application logic:

const [partnerName]Events = events.filter(event =>
  event.[partnerName]Relationship === '[PARTNERNAME]_OWNED' ||
  event.[partnerName]Relationship === '[PARTNERNAME]_SPONSORED'
);

Use Case: Feature [partner name]-affiliated events prominently.

Complete Event Details​

Get all available information for an event.

query {
  getEventById(id: 12345) {
    # Basic Info
    id
    name { en }
    description { en { text isAiGenerated } }
    permalink

    # Location
    city { en }
    location { en }
    country {
      isoCode
      names { en }
    }
    lonlat

    # Dates & Status
    startDate
    editionStatus {
      code
      names { en }
    }
    eventStatus {
      code
      names { en }
    }

    # Registration
    isRegistrationOpen
    checkoutUrl
    eventPageUrl
    localizedEventPageUrl { en }

    # Branding
    [partnerName]Relationship
    [partnerName]Image
    isAhotuEvent

    # Races
    races {
      id
      raceName
      distanceKm
      startDate
      startTime
      participant {
        code
        names { en }
      }
      activities {
        distance
        distanceKm
        elevationGain
        courseProfile {
          names { en }
        }
        courseType {
          names { en }
        }
        terrain {
          names { en }
        }
        environment {
          names { en }
        }
      }
    }

    # Metadata
    updatedAt
  }
}

Use Case: Comprehensive event detail page with all information.

Best Practices​

1. Request Only What You Need​

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

# Avoid - Over-fetching
query {
  events(page: 0, size: 10) {
    data {
      # Don't request all fields if you only need a few
    }
  }
}

2. Use Appropriate Page Sizes​

  • List views: size: 20
  • Map markers: size: 50-100
  • Infinite scroll: size: 20 per load

3. Filter Early​

Apply filters to reduce the result set before pagination.

4. Cache Responses​

Cache query results on the client side to avoid redundant API calls.

5. Handle Errors Gracefully​

try {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ query })
  });

  const data = await response.json();

  if (data.errors) {
    console.error('GraphQL errors:', data.errors);
    // Handle errors
  }

  return data.data;
} catch (error) {
  console.error('Network error:', error);
  // Handle network errors
}

Next Steps​