API Tenant Customization

Overview

The Events Content Calendar API uses a multi-tenant architecture that allows each client to have a fully customized API experience. This approach ensures you receive only the data relevant to your business needs, improving performance, reducing integration complexity, and aligning the API with your specific use cases.

Multi-Tenant Architecture

What is API Tenancy?

Each API client operates within their own tenant—a logically isolated view of the event catalog configured specifically for their requirements. While all tenants share the same underlying infrastructure and data sources, each tenant's API responses are filtered and customized based on their configuration.

Benefits:

Relevant Data Only: Your API returns only events that match your business domain
Simplified Integration: Fewer irrelevant results mean simpler client-side filtering
Optimized Performance: Smaller result sets improve query response times
Cost Efficiency: Reduced bandwidth usage with focused data
Business Alignment: API behavior matches your product requirements

tip

Think of a tenant as your personalized lens into the global event catalog—you see exactly what you need, nothing more, nothing less.

Customization Dimensions

1. Sport Filtering

Limit your API catalog to specific sports relevant to your audience.

Examples:

Business Type	Sport Configuration
Running Platform	`run`, `trail_run`
Triathlon Site	`triathlon`, `duathlon`
Cycling App	`cycling`, `mountain_bike`
Multi-Sport Portal	All available sports

Impact:

Events outside your sport selection are completely excluded from queries
Improves search relevance for your users
Reduces query complexity and response size

# With running-only tenant, this query automatically filters to running events
query {
  events(page: 0, size: 20) {
    data {
      sport {
        code  # Will only return 'run' or 'trail_run'
      }
    }
  }
}

2. Geographic Scoping

Restrict events to specific countries or regions.

Examples:

Use Case	Geographic Configuration
US-Only Platform	Countries: `["US"]`
European Market	Countries: `["FR", "DE", "IT", "ES", "UK", ...]`
North America	Countries: `["US", "CA", "MX"]`
Global Platform	All countries

Benefits:

Regional focus aligns with your target market
Reduces noise from irrelevant international events
Improves localization consistency
Supports compliance with regional data requirements

note

Geographic scoping is particularly valuable for platforms serving specific markets or those with localized content strategies.

3. Language Selection

Choose which languages your API supports for localized content.

Available Languages:

English (en, en_US, en_GB)
Spanish (es, es_419)
French (fr)
German (de)
Italian (it)
Portuguese (pt, pt_BR)
Dutch (nl)
Swedish (sv)
Russian (ru)
Japanese (ja)
Korean (ko)
Chinese (zh, zh_HANT)
Thai (th)
Turkish (tr)
Indonesian (id)

Configuration Options:

Primary Language: Your default/main language
Secondary Languages: Additional supported languages
Fallback Strategy: How to handle missing translations

Example Configuration:

{
  primaryLanguage: "en",
  supportedLanguages: ["en", "es", "fr"],
  fallbackLanguage: "en"
}

4. Feature Control

Enable or disable specific event attributes and data fields.

Configurable Features:

Feature	Description	Use Case
Enhanced Descriptions	Include additional event descriptions	Enable for enhanced content
[Partner Name] Branding	Include [partner name] relationship data	Enable for [partner name] partnerships
Registration URLs	Allow users to register for events	Enable effortless registration and a seamless experience for your audience
Historical Data	Include past event editions	Enable for analysis features
Course Details	Include elevation, terrain, profile data	Enable for detailed race info
Localized URLs	Include language-specific event URLs	Enable for multi-language sites

Example:

query {
  events(page: 0, size: 10) {
    data {
      description {
        en {
          text
        }
      }
      [partnerName]Relationship  # Only if [partner name] branding enabled
      checkoutUrl       # Only if registration URLs enabled
    }
  }
}

5. Custom Catalogs

Some clients require multiple tenant configurations for different products or business lines. This allows you to maintain different event catalogs under one tenant for various use cases.

Multi-Catalog Scenarios:

Brand Segmentation
- Premium brand catalog (curated events)
- Mass market brand catalog (all events)
Product Differentiation
- Training app catalog (beginner-friendly events)
- Performance app catalog (competitive events)
Geographic Variants
- US catalog
- European catalog
- Asian catalog

note

Custom catalogs enable filtering events by specific criteria, though filtering by these specific attributes may not be available in all API queries. Each catalog receives its own configuration, accessed via the same API endpoints but returning different filtered results.

Tenant Configuration Process

1. Discovery Phase

We work with you to understand your business needs:

Key Questions:

What is your primary business focus?
Which sports are relevant to your audience?
What geographic markets do you serve?
What languages does your platform support?
What features are essential for your use case?
Do you need multiple catalogs?

2. Configuration Design

Based on discovery, we design your tenant configuration:

Sample Configuration Document:

tenant:
  id: "your-company-prod"
  name: "Your Company Production"

  catalog:
    sports:
      - run
      - trail_run

    geography:
      countries:
        - US
        - CA
      regions: []  # All regions within selected countries

    languages:
      primary: en
      supported:
        - en
        - es
      fallback: en

    features:
      enhancedDescriptions: true
      [partnerName]Data: false
      registrationUrls: true
      historicalData: false
      courseDetails: true
      localizedUrls: true

    filters:
      excludeCanceled: true
      excludeIncomplete: true

3. Implementation & Testing

We implement your configuration and provide a test environment:

Testing Process:

Configuration deployed to development environment
Test credentials provided
GraphQL Playground access for exploration
Sample queries demonstrating configuration
Feedback and adjustment iterations

4. Production Deployment

After approval, configuration is deployed to production:

Deliverables:

Production API credentials
Endpoint URLs (dev, preprod, prod)
Configuration documentation
Query examples tailored to your catalog
Support contact information

Tenant Management

Configuration Updates

Tenant configurations can evolve as your business needs change.

Update Process:

Request configuration change
Review impact assessment
Test in development environment
Schedule production deployment
Verify changes in production

Common Updates:

Add/remove sports
Expand to new countries
Add language support
Enable additional features
Adjust quality thresholds

warning

Configuration changes affect all API responses. Always test thoroughly in development before production deployment.

Environment Strategy

Each tenant has access to multiple environments:

Environment	Purpose	Data
Development	Integration testing, exploration	Test data + production sample
Preproduction	Final testing before go-live	Production data snapshot
Production	Live application traffic	Real-time production data

Best Practices:

Develop and test in Development
Final validation in Preproduction
Deploy to Production only after thorough testing
Use separate credentials for each environment

Use Case Examples

Example 1: Running-Only Platform (US)

Business: Marathon training app targeting US runners

Configuration:

sports: [run, trail_run]
countries: [US]
languages: [en]
features:
  enhancedDescriptions: true
  courseDetails: true
  registrationUrls: true

Result:

API returns only US running and trail events
All events include course details for training planning
Registration URLs enable seamless user experience
English-only content matches app localization

Example 2: European Multi-Sport Portal

Business: General sports event listing site for Europe

Configuration:

sports: [run, trail_run, cycling, triathlon, swimming]
countries: [FR, DE, IT, ES, UK, NL, BE, AT, CH]
languages: [en, fr, de, it, es, nl]
features:
  enhancedDescriptions: true
  courseDetails: true
  registrationUrls: true
  localizedUrls: true

Result:

Wide sport coverage for diverse audience
Multi-country European focus
6 language support for localization
Localized URLs for better user experience

Example 3: [Partner Name] Partnership Platform

Business: [Partner name]-branded event discovery app

Configuration:

sports: [run, trail_run]
countries: [US, CA, UK, FR, DE, IT, ES, JP, CN]
languages: [en, es, fr, de, it, ja, zh]
features:
  [partnerName]Data: true
  [partnerName]Image: true
  registrationUrls: true
  courseDetails: true

Result:

[Partner name] relationship flags for featuring sponsored events
[Partner name] event imagery for branded experience
Global coverage for [partner name]'s market presence
Multi-language for international users

Example 4: Training Plan Integration

Business: Fitness app with integrated race calendar

Configuration:

sports: [run]
countries: [US, CA]
languages: [en]
distanceTypes: [_5k, _10k, half_marathon, marathon]
courseProfiles: [flat, undulating]  # Exclude extreme courses
features:
  courseDetails: true
  enhancedDescriptions: false
  registrationUrls: true

Result:

Standard distances align with training plans
Exclude difficult courses unsuitable for most users
Detailed course info for training recommendations
Focused catalog reduces user choice overload

Performance Implications

Query Performance

Tenant customization directly improves query performance:

Without Tenant Filtering:

Query: All marathon events
Result Set: 5,847 events globally
Response Time: ~450ms

With Tenant Filtering (US Running):

Query: All marathon events
Result Set: 892 US events
Response Time: ~180ms

Improvement: 60% faster response time

Bandwidth Optimization

Smaller, focused datasets reduce bandwidth consumption:

Example Event Response Size:

Full catalog (all sports, all countries): ~2.3 KB per event
Filtered catalog (specific sports, countries): ~1.8 KB per event
20% reduction in bandwidth per event

Annual Impact (1M API calls):

Full catalog: ~2.3 GB data transfer
Filtered catalog: ~1.8 GB data transfer
Savings: 500 MB annually

Best Practices

1. Start Focused, Expand Later

Begin with a narrow configuration matching your MVP requirements. You can always expand later.

Recommended Approach:

Phase 1: Core sport(s) + primary market + single language
Phase 2: Add secondary languages
Phase 3: Expand to adjacent markets
Phase 4: Add related sports

2. Align with User Personas

Configure your tenant based on actual user needs, not hypothetical future requirements.

Questions to Ask:

What sports do 90% of my users care about?
What percentage of my users are in each country?
Which languages are actively used in my application?

3. Monitor Usage Patterns

After launch, analyze which filters your users apply most often. Consider moving common filters into your tenant configuration.

Example: If 95% of queries filter to distanceTypes: [marathon, half_marathon], consider configuring your tenant to only include those distances.

4. Leverage Multiple Catalogs Strategically

Use multiple catalogs when serving truly distinct audiences, not as a workaround for filtering.

Good Use: Separate catalogs for consumer app vs. B2B partner API Avoid: Separate catalogs for minor feature differences

5. Test Configuration Changes Thoroughly

Always test in development before requesting production changes.

Testing Checklist:

Verify expected events are included
Confirm excluded events are absent
Test all critical query patterns
Check facet results for accuracy
Validate multi-language content

Support & Modifications

Requesting Configuration Changes

Process:

Contact your account manager or support team
Describe desired changes and business rationale
Receive impact assessment and timeline
Test changes in development environment
Approve production deployment

Typical Turnaround:

Simple changes (add country): 1-2 business days
Complex changes (new features): 1-2 weeks
Emergency changes: Same-day (subject to availability)

Configuration Review

We recommend periodic configuration reviews to ensure ongoing alignment with your business needs.

Review Cadence: Quarterly or after major product launches

Review Topics:

Usage analytics and patterns
Feature adoption
Performance metrics
Upcoming business changes
Platform roadmap

Next Steps

📊 Review Catalog Statistics to understand available data
💼 Explore Business Benefits to see platform capabilities
📝 Check Query Examples to understand API usage
📞 Contact your account manager to discuss your tenant configuration needs

Overview​

Multi-Tenant Architecture​

What is API Tenancy?​

Customization Dimensions​

1. Sport Filtering​

2. Geographic Scoping​

3. Language Selection​

4. Feature Control​

5. Custom Catalogs​

Tenant Configuration Process​

1. Discovery Phase​

2. Configuration Design​

3. Implementation & Testing​

4. Production Deployment​

Tenant Management​

Configuration Updates​

Environment Strategy​

Use Case Examples​

Example 1: Running-Only Platform (US)​

Example 2: European Multi-Sport Portal​

Example 3: [Partner Name] Partnership Platform​

Example 4: Training Plan Integration​

Performance Implications​

Query Performance​

Bandwidth Optimization​

Best Practices​

1. Start Focused, Expand Later​

2. Align with User Personas​

3. Monitor Usage Patterns​

4. Leverage Multiple Catalogs Strategically​

5. Test Configuration Changes Thoroughly​

Support & Modifications​

Requesting Configuration Changes​

Configuration Review​

Next Steps​

Overview

Multi-Tenant Architecture

What is API Tenancy?

Customization Dimensions

1. Sport Filtering

2. Geographic Scoping

3. Language Selection

4. Feature Control

5. Custom Catalogs

Tenant Configuration Process

1. Discovery Phase

2. Configuration Design

3. Implementation & Testing

4. Production Deployment

Tenant Management

Configuration Updates

Environment Strategy

Use Case Examples

Example 1: Running-Only Platform (US)

Example 2: European Multi-Sport Portal

Example 3: [Partner Name] Partnership Platform

Example 4: Training Plan Integration

Performance Implications

Query Performance

Bandwidth Optimization

Best Practices

1. Start Focused, Expand Later

2. Align with User Personas

3. Monitor Usage Patterns

4. Leverage Multiple Catalogs Strategically

5. Test Configuration Changes Thoroughly

Support & Modifications

Requesting Configuration Changes

Configuration Review

Next Steps