Skip to main content

GraphQL Schema Reference

Welcome to the Ahotu Events API GraphQL Schema Reference. This section provides comprehensive, auto-generated documentation for all types, queries, inputs, and enums available in our GraphQL API.

What is GraphQL?​

GraphQL is a query language for APIs that gives you:

  • Precise Data Fetching: Request exactly the fields you need, nothing more
  • Single Request: Get related data in one query instead of multiple REST calls
  • Strongly Typed: Schema-defined types ensure data consistency
  • Self-Documenting: Introspection allows tools to understand the API structure

API Endpoint​

https://api.ahotu.com/graphql

Quick Start​

Basic Event Query​

query GetEvents {
  events(page: 0, size: 10, sort: date_asc) {
    data {
      id
      name {
        en
      }
      startDate
      city {
        en
      }
      country {
        names {
          en
        }
      }
    }
    totalCount
    pageInfo {
      currentPage
      hasNextPage
    }
  }
}

Query with Filters​

query SearchMarathons {
  events(
    criteria: {
      distanceTypes: [marathon]
      sports: [run]
      dateRange: {
        dateFrom: "2025-01-01"
        dateTo: "2025-12-31"
      }
    }
    page: 0
    size: 20
    sort: date_asc
  ) {
    data {
      id
      name {
        en
      }
      startDate
      distancesInKm
    }
    totalCount
  }
}
query NearbyEvents {
  events(
    criteria: {
      around: {
        point: { lat: 40.7128, lon: -74.0060 }
        distance: "50km"
      }
    }
    sort: geopoint_asc
  ) {
    data {
      id
      name {
        en
      }
      city {
        en
      }
      lonlat
    }
  }
}

Schema Organization​

The schema is organized into the following sections:

Operations​

  • Queries: Top-level query operations (events, getEventById, getRaceById)
  • Directives: GraphQL directives for conditional field inclusion

Types​

Core Types​

  • Event: Main event type with all event details
  • Race: Individual race within an event
  • Activity: Detailed activity information for each race
  • Events/Races: Paginated result containers

Supporting Types​

  • LocalizedString: Multi-language string support
  • LocalizedDescription: Multi-language description with AI generation flag
  • LocalizedCountry: Country information with names in all languages
  • Facets: Aggregated search results for filtering
  • PageInfo: Pagination metadata

Input Types​

  • searchCriteria: Main filter input for event queries
  • DateRange: Filter by date range
  • DistanceRange: Filter by distance range
  • Around: Geo-spatial filtering
  • Point: Geographic coordinates

Enums​

  • SportEnum: Sport types (run, trail_run)
  • DistanceTypeEnum: Standard race distances (_5k, _10k, half_marathon, marathon, other)
  • CourseProfileEnum: Terrain difficulty (flat, undulating, hilly, extreme)
  • CourseTypeEnum: Course layout (point_to_point, out_and_back, single_loop, loops)
  • TerrainEnum: Surface types (road, trail, track, etc.)
  • EnvironmentEnum: Race environment tags (city, mountain, beach, etc.)
  • ParticipationEnum: Participation types (solo, relay, team)
  • OtherEnum: Additional race characteristics
  • Region1Enum/Region2Enum: Geographic regions (states, provinces, etc.)
  • SortType: Sorting options
  • Unit: Measurement units

Authentication​

All API requests require OAuth2 authentication. See the Authentication guide for details.

Best Practices​

  1. Request Only Needed Fields: GraphQL allows precise field selection
  2. Use Fragments: Reuse field selections with GraphQL fragments
  3. Implement Pagination: Use page and size parameters for large result sets
  4. Leverage Facets: Use faceted search for better user filtering experience
  5. Cache Responses: Implement caching based on query complexity and data volatility

Support​

Browse the Schema​

Use the navigation menu to explore:

  • Operations: Available queries and directives
  • Types: All GraphQL types with field definitions
  • Enums: Enumeration values and their meanings
  • Inputs: Input types for filtering and searching
  • Scalars: Primitive types