US School Directory — NCES + Licensed GreatSchools API

Find US K–12 school records from the public NCES Common Core of Data directory, and optionally retrieve GreatSchools ratings and directory fields through your own authorized NearbySchools API agreement. This actor does not crawl, harvest, or scrape GreatSchools web pages.

Use cases

• Enrich a known list of NCES school IDs with directory fields.
• Retrieve schools around a coordinate through a licensed GreatSchools NearbySchools API key.
• Feed normalized school records into location intelligence, education research, or internal data pipelines.

Do not use it to collect GreatSchools content without an API agreement, create marketing-contact lists, or bypass GreatSchools access controls.

Input

NCES directory mode

The default mode accepts 12-digit NCES school IDs. This uses the public NCES-backed directory endpoint and needs no secret.

{
  "sourceMode": "nces",
  "ncesSchoolIds": ["010000500870"],
  "maxResults": 10
}

Authorized GreatSchools API mode

Create an Actor environment variable named GREAT_SCHOOLS_API_KEY in Apify Console using an API key issued under your NearbySchools agreement. Never supply that key as an actor input value.

{
  "sourceMode": "greatschoolsApi",
  "greatSchoolsLocation": {
    "latitude": 37.7940627,
    "longitude": -122.2680029,
    "distanceMiles": 5
  },
  "maxResults": 10
}

auto selects the GreatSchools API when a location is supplied; otherwise it selects NCES mode.

Output

Every record has a stable, agent-friendly shape. Fields unavailable from a source are null.

{
  "schoolName": "Alameda High School",
  "source": "greatschoolsApi",
  "ncesSchoolId": "060177000041",
  "greatSchoolsUniversalId": "0600001",
  "greatSchoolsRating": 10,
  "address": "2201 Encinal Avenue",
  "city": "Alameda",
  "state": "CA",
  "districtName": "Alameda Unified School District",
  "sourceUrl": "https://gs-api.greatschools.org/nearby-schools",
  "scrapedAt": "2026-07-22T12:00:00.000Z"
}

Pricing configuration

Before publishing, configure both Pay Per Event and Pay Per Usage in Apify Console. The included event contract contains:

Event	Suggested launch price
apify-actor-start	$0.00005/run
school-record-returned	$0.005/record

Enable compute-unit and proxy pass-through for Pay Per Usage. The GreatSchools API may separately charge under your agreement; choose a record price that preserves your required margin.

Compliance and data provenance

NCES mode uses directory data. GreatSchools values are made only through the documented API and your own credentials; GreatSchools web content is never scraped. You are responsible for ensuring your API agreement, data use, retention, attribution, and redistribution comply with the applicable provider terms and law.

MCP routing

Use this actor for structured US K–12 school directory records or for authorized NearbySchools API results. Do not use it for web-page scraping, reviews, parent contact details, enrollment applications, or any school outside the United States.

Frequently asked questions

Can I schedule US School Directory — NCES + Licensed GreatSchools API?

Yes. Use an Apify schedule to run the same saved input at a chosen interval, then connect a webhook or integration to process the dataset when the run finishes.

How should I test a new input?

Begin with the prefilled example or a small limit. Confirm that the output fields, source coverage, runtime, and live charges match your workflow before increasing the scope.

How do I export the results?

Open the run's default dataset in Apify Console and export JSON, CSV, Excel, XML, or RSS. Applications can retrieve the same records through the Apify API client or REST dataset endpoint.

Can an AI agent call this Actor?

Yes. Add muhammadafzal/greatschools-nces-directory through the hosted Apify MCP server or call it through the API. The Actor's input and dataset schemas help agents construct valid requests and interpret returned records.

Recommended workflow

1. Define the smallest useful scope. Choose a representative public URL, query, identifier, or filter and keep the first result limit low.
2. Run and inspect. Check the run log, dataset item count, field coverage, source URLs, and live event or usage charges.
3. Validate downstream assumptions. Confirm nullable fields, deduplication keys, timestamps, and any locale-specific formats before importing records into another system.
4. Scale gradually. Increase limits or scheduling frequency only after the small run behaves as expected. Use Apify's maximum-cost and timeout controls to bound large jobs.
5. Monitor changes. Keep a small known-good input as a canary. If the source layout or API changes, compare the new dataset with a previously validated run and report the run ID when requesting support.

For recurring workflows, store the exact Actor input with your pipeline configuration. This makes runs reproducible and helps distinguish a source-data change from an input change.