Product Overview

SDX ID

Universal, open identifiers for every foundational sports entity: events, competitions, participants, venues, and organizations. Cross-mapped to every major provider so you can connect data across your entire ecosystem.

THE SCHEMA: FOUNDATIONAL + MEDIA EVENTS

SDX breaks sports into its fundamentals. The schema covers 10 entity types across two layers: the foundational sports layer (competitions, events, teams, persons, venues, organizations, phases, sports) and a media layer that bridges sports data with broadcast identifiers.

THE EIDR BRIDGE

The SDX Media Event is a live sports broadcast, the entity that lives in both worlds. It connects to an SDX Event (the game itself) and can carry an EIDR ID (the broadcast registration). When an EIDR member registers a live sports broadcast, they include the SDX Media Event ID, connecting the EIDR record back to the game, teams, venue, and full sports context.

SDX CLI Tool

A local-first command-line tool that downloads the SDX entity catalog, matches your data against it, and writes IDs directly into your tables. No services to host, no data to send out. Everything runs in your environment.

• Single Binary

  Install in seconds. Runs on Linux (x86_64, arm64), macOS (arm64, x86_64), and Windows (x86_64). Zero dependencies.

• Your Data Stays Yours

  Everything runs locally in your environment. Customer data never leaves. Only an API key is sent to SDX for catalog downloads.

• Database Support

  Supports Postgres, MySQL, and SQL Server out of the box. Connect with a standard DATABASE_URL environment variable.

FOUR-STEP WORKFLOW

The typical SDX workflow has four commands, run in order. Once set up, they can run on a schedule (cron) and keep your IDs up to date automatically.

1. 1
   Download the entity catalog

   bash

   sdx catalog sync

   Downloads the SDX entity catalog as a local SQLite file. First run gets a full compressed snapshot; subsequent runs download only incremental changesets (small binary deltas). If your catalog is more than 7 days behind, the CLI automatically fetches a fresh snapshot.

2. 2
   Download partner ID mappings

   bash

   sdx mappings sync

   Downloads partner provider ID mapping files from the URLs configured in your sdx.yml. These mappings enable exact ID matching during resolution, the highest-confidence path. Files are cached locally with HTTP caching to avoid unnecessary downloads.

3. 3
   Match rows & write SDX IDs

   bash

   sdx sync sdx

   The primary resolution command. It selects rows that don't yet have an SDX ID, tries to find a match (exact match via partner mappings first, then fuzzy matching against the catalog), and writes the result. One match writes the ID; zero matches marks the row as unresolved; multiple candidates marks it as needs_review. The command is idempotent and safe to run frequently. It only touches rows with a NULL SDX ID column.

4. 4
   Resolve non-partner IDs

   bash

   sdx sync <provider>

   Resolves IDs for non-partner providers using the SDX ID as a bridge. Calls your fetch script to get the provider's entity list as JSON, resolves each against the SDX catalog, and writes the provider ID to your rows via the SDX ID bridge.

QUICK INSTALL

curl -fsSL https://sdx.sportsdata.io/install.sh | sh

Or download the binary directly from the SDX website and place it in your PATH. Verify the installation:

sdx --version

Then sync the catalog and resolve your IDs:

sdx catalog sync && sdx sync sdx

CONFIGURATION

The CLI is configured with an sdx.yml file in your project directory. This file tells the CLI which database tables contain sports entities, how to match them, and where to write IDs. It has two sections: providers (define the data sources whose IDs appear in your database) and entities (map your database tables to SDX entity types).

# sdx.yml — example configuration
providers:
  sdx:
    name: "SDX"
    type: partner
  partner_a:
    name: "Partner A"
    type: partner
    mappings:
      entities:
        player:
          url: "https://data.partner-a.com/sdx/mappings/players.json"

entities:
  - competition: comp_xxxxx
    entity: player
    table: mlb_players
    primary_key: id
    match_fields:
      name: [first_name, last_name]
      team: [mlb_teams.location, mlb_teams.mascot]
    provider_ids:
      sdx:
        column: sdx_id
      partner_a:
        column: partner_a_id

REVIEWING & STATUS TRACKING

When the CLI encounters rows that can't be resolved (either no match found or multiple candidates returned), it logs them to a CSV file for manual review. Use sdx review to see a summary of resolution status across all your entities and providers: how many are resolved, unresolved, or need review. Filter by competition, entity type, or provider as needed.

SAFETY GUARANTEES

• Never overwrites existing IDs

  all writes are guarded with AND column IS NULL

• Fully idempotent

  safe for cron scheduling. Overlapping runs may cause wasted work, but never corruption.

• Data stays local

  fetch scripts run in your environment with your credentials. Provider API keys never touch SDX infrastructure.

ACCOUNT TIERS

• Free

  Daily catalog syncs

• Pro

  Hourly catalog syncs

• Enterprise

  Unlimited catalog syncs

Marketplace — Partner Mappings

The SDX ID and CLI Tool let you connect. Partner mappings turn connection into a network. As more partners publish mappings, the value compounds for everyone. The network effect is the product.

HOW IT WORKS

1. Create

   Build your SDX mappings using the CLI tool. Match your data to SDX IDs. The CLI handles the heavy lifting with exact and fuzzy matching.

2. Publish

   Publish your mappings as an encrypted partner catalog in the SDX Marketplace. Your catalog becomes available for others to consume.

3. Share

   Share catalogs openly with the ecosystem, or privately with trusted partners via secret keys. You control who can access your mappings.

4. Use

   When you consume a partner's catalog, the CLI handles the resolution automatically. Partner mappings provide the highest-confidence match path, so only edge cases need manual review.

CATALOG TYPES

• Open Catalogs

  Available to anyone in the ecosystem. Maximize reach and interoperability. Ideal for organizations that want broad adoption of their ID mappings.

• Private Catalogs

  Shared with trusted partners via secret keys. Full control over your data and IP. Perfect for commercial partnerships or proprietary data relationships.

CLI Quick Reference

All available commands at a glance.