How to Consume Our Data

The reconstruction contract

Given partners.json plus each partner's referenced events.json and past-events.json files, no other data source — no API key, no database, no source code — is needed to fully reproduce this site's opportunity data. Every file below is a plain, publicly-served JSON file with no authentication.

These files are generated at build/publish time by the scraper pipeline (export/publish.py::project()) and served as static assets. This page never fetches them live — everything shown below is a hand-authored, static example of the real shape, kept accurate by an automated field-name check.

A note on naming

The pipeline's own curated partner roster (the input it reads) also happens to be named partners.json, but lives at a different path and has a different shape. This page documents only the published output, public/data/partners.json — not the curated input file. Don't confuse the two.

File 1: the partner roster — partners.json

Served at /data/partners.json. A single JSON object: an envelope of generated_at (an ISO 8601 UTC timestamp) and partner_count, wrapping a partners array. Every element is a partner organization record — its directory fields (name, description, location, website, contact info, logo, etc.) plus three fields added specifically for this contract:

File 2: per-partner events — events.json / past-events.json

Served at /data/partners/<slug>/events.json and /data/partners/<slug>/past-events.json, one pair per partner listed in partners.json. Each file is a JSON object with the same envelope shape:

current and past are a true partition, not an independent filter: every event this pipeline has ever recorded for a partner lands in exactly one of the two files (undated records included, in past-events.json) — nothing is silently dropped.

Event field reference

Every event record in events carries exactly these fields (the site's canonical schema, export.writer.SITE_SCHEMA_FIELDS):

File 3: the robot teams directory — teams.json

Served at /data/teams.json (sprint 017). A single JSON object, independent of Files 1–2 above: a self-describing meta envelope wrapping a teams array — the FIRST/VEX robotics teams directory for San Diego County. No other data source is needed to interpret it.

Every element of teams carries exactly these fields (the site's canonical team schema, teams.export.TEAMS_SCHEMA_FIELDS):

{
  "team_id": "ftc-1622",
  "league": "FTC",
  "program": "FIRST Tech Challenge",
  "number": "1622",
  "name": "Example Robotics",
  "organization": "Example High School",
  "org_type": "school",
  "city": "San Diego",
  "postal_code": "92101",
  "latitude": 32.7157,
  "longitude": -117.1611,
  "location_precision": "school",
  "in_region": true,
  "matched_name": "Example High School",
  "needs_review": false,
  "website": "",
  "website_status": "",
  "organization_website": "",
  "social": [],
  "rookie_year": 2015,
  "active": true,
  "last_season": 2025,
  "sponsors": ["Example Robotics Boosters"],
  "sponsor_provenance": {"Example Robotics Boosters": "structured"},
  "org_key": "",
  "sibling_team_ids": []
}

Worked example

A trimmed partners.json entry for a hypothetical partner, and its matching events.json — hand-authored, not fetched, to illustrate the shape (Design Rationale D3: these files may not exist yet in every checkout).

Trimmed entry from partners.json

{
  "generated_at": "2026-08-27T12:00:00Z",
  "partner_count": 1,
  "partners": [
    {
      "id": 42,
      "name": "Example STEM Center",
      "organization_type": "Museum",
      "location": "1234 Discovery Way, San Diego, CA 92101",
      "latitude": 32.7157,
      "longitude": -117.1611,
      "website": "https://example-stem-center.org/",
      "logo_src": "example-stem-center.png",
      "slug": "example-stem-center",
      "events_url": "partners/example-stem-center/events.json",
      "past_events_url": "partners/example-stem-center/past-events.json"
    }
  ]
}

Matching partners/example-stem-center/events.json

{
  "generated_at": "2026-08-27T12:00:00Z",
  "partner_slug": "example-stem-center",
  "kind": "current",
  "event_count": 1,
  "events": [
    {
      "slug": "family-robotics-night_20260915",
      "title": "Family Robotics Night",
      "partner_name": "Example STEM Center",
      "partner_id": 42,
      "description": "Build and race simple robots together as a family.",
      "link": "https://example-stem-center.org/events/robotics-night",
      "availability": "",
      "date_start": "2026-09-15T18:00:00-07:00",
      "date_end": "2026-09-15T20:00:00-07:00",
      "age_grade_level": ["Elementary", "Middle School"],
      "cost_range": "Free",
      "time_of_day": ["Evening"],
      "opportunity_type": "Out-of-school Programs",
      "areas_of_interest": ["Technology", "Engineering"],
      "specific_attention": [],
      "financial_support": "No",
      "ngss_aligned": "No",
      "location": "1234 Discovery Way, San Diego, CA 92101",
      "latitude": "32.7157",
      "longitude": "-117.1611",
      "contact_name": "",
      "contact_email": "",
      "contact_phone": "",
      "logo_src": "example-stem-center.png",
      "eligibility": "",
      "image_src": ""
    }
  ]
}

This same contract is what powers the site you're already looking at — browse the Partner Directory to see it rendered.