# US School Directory API — NCES + GreatSchools (`muhammadafzal/greatschools-nces-directory`) Actor

Find U.S. K–12 school directory records from NCES and enrich nearby schools through your authorized GreatSchools NearbySchools API. No GreatSchools web scraping.

- **URL**: https://apify.com/muhammadafzal/greatschools-nces-directory.md
- **Developed by:** [Muhammad Afzal](https://apify.com/muhammadafzal) (community)
- **Categories:** Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 school record returneds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 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.

```json
{
  "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.

```json
{
  "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`.

```json
{
  "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.

# Actor input Schema

## `sourceMode` (type: `string`):

Use this when choosing the data provider. Select 'nces' for public NCES directory records, 'greatschoolsApi' only with an authorized NearbySchools API key, or 'auto' to select from your input. This is not a GreatSchools web-scraping option.

## `ncesSchoolIds` (type: `array`):

Use this when you already know one or more 12-digit NCES school IDs, for example '010000500870'. The actor retrieves public NCES directory records by ID. This is not a GreatSchools universal ID.

## `greatSchoolsLocation` (type: `object`):

Use this when searching nearby schools through your authorized GreatSchools NearbySchools API key. Provide latitude and longitude such as 37.7940627 and -122.2680029. It is not used for NCES ID lookups.

## `maxResults` (type: `integer`):

Use this when limiting returned schools. Choose a whole number from 1 to 50; the default is 10. GreatSchools API requests cannot return more than 50 results per page.

## Actor input object example

```json
{
  "sourceMode": "nces",
  "ncesSchoolIds": [
    "010000500870"
  ],
  "maxResults": 5
}
```

# Actor output Schema

## `results` (type: `string`):

Link to normalized school records.

## `summary` (type: `string`):

Source, result count, and any non-fatal warnings.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "sourceMode": "nces",
    "ncesSchoolIds": [
        "010000500870"
    ],
    "maxResults": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("muhammadafzal/greatschools-nces-directory").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "sourceMode": "nces",
    "ncesSchoolIds": ["010000500870"],
    "maxResults": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("muhammadafzal/greatschools-nces-directory").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "sourceMode": "nces",
  "ncesSchoolIds": [
    "010000500870"
  ],
  "maxResults": 5
}' |
apify call muhammadafzal/greatschools-nces-directory --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,muhammadafzal/greatschools-nces-directory"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/NPnfCywON5CkWNADL/builds/l6tm8jvbfFoBzxRbg/openapi.json