> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Schools

> List the public or private schools near a point, or the schools of a US public school district, with address, grades, enrolment and teachers.

Lists US public schools (Common Core of Data) or private schools (Private School Survey) of the US National Center for Education Statistics within a distance of a point, nearest first, or every school of a public school district: name, address, county, grade range, kind, charter and virtual status, enrolment, teachers and student-teacher ratio. Private schools carry no enrolment.

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

**school\_type** `string` *required*

public for the Common Core of Data, private for the Private School Survey. One of `public`, `private`.

**latitude** `number`

Latitude in decimal degrees, for example 42.2808. From -90 to 90.

**longitude** `number`

Longitude in decimal degrees (west is negative), for example -83.743. From -180 to 180.

**radius\_km** `number`

Distance from the point in kilometres, 0.5 to 10. From 0.5 to 10. Defaults to `2`.

**district\_id** `string`

The seven-digit NCES district id (LEAID), for example 2602820 for Ann Arbor Public Schools; public schools only. district\_id is the seven-digit NCES district id.

**limit** `integer`

Most schools to return, 1 to 50. From 1 to 50. Defaults to `20`.

<Snippet file="audit-context-params.mdx" />

## Response (200 OK)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

**data.request\_id** `string`

Durable job ID for audit and lookup

**data.status** `string`

Job status: `completed`

**data.tool** `string`

Always `place_schools`

**data.result** `object`

The answer, described under Result below

**data.evidence** `object`

Where the answer came from and when

**data.evidence.source** `string`

The public body the data comes from. Always `US National Center for Education Statistics`.

**data.evidence.source\_kind** `string`

`public` when the data comes from a public body, `commercial` otherwise

**data.evidence.retrieved\_at** `string`

When the lookup was made, as an ISO 8601 UTC time

**data.evidence.as\_of** `string | null`

When the source says the fact was last updated, or `null` when the source gives no date

## Result

Nested under `data.result`.

**data.result.school\_type** `string`

The collection searched.

**data.result.total** `number`

Schools the source returned for the point or district, at most 2,000.

**data.result.more** `boolean`

True when more schools were returned than listed, or the source held more than 2,000.

**data.result.schools** `object[]`

The schools, nearest first for a point, in name order for a district, up to the limit.

**data.result.schools\[].id** `string`

The NCES school id (public) or private school id.

**data.result.schools\[].name** `string`

The school's name.

**data.result.schools\[].district\_id** `string | null`

The NCES district id; null for private.

**data.result.schools\[].district\_name** `string | null`

The district's name; null for private.

**data.result.schools\[].address** `string | null`

Street address. `null` when the source gives no value.

**data.result.schools\[].city** `string | null`

City or town. `null` when the source gives no value.

**data.result.schools\[].state** `string | null`

Two-letter state code. `null` when the source gives no value.

**data.result.schools\[].zip\_code** `string | null`

ZIP code. `null` when the source gives no value.

**data.result.schools\[].county** `string | null`

County. `null` when the source gives no value.

**data.result.schools\[].phone** `string | null`

Telephone; null for private.

**data.result.schools\[].level** `string | null`

School level, for example Elementary; null for private.

**data.result.schools\[].kind** `string | null`

Kind of school, for example Regular School; null for private.

**data.result.schools\[].charter** `boolean | null`

Whether the school is a charter school; null when not stated.

**data.result.schools\[].virtual** `string | null`

Virtual status, for example Not Virtual. `null` when the source gives no value.

**data.result.schools\[].lowest\_grade** `string | null`

Lowest grade offered, for example KG. `null` when the source gives no value.

**data.result.schools\[].highest\_grade** `string | null`

Highest grade offered, for example 05. `null` when the source gives no value.

**data.result.schools\[].status** `string | null`

Status this school year, for example Open; null for private.

**data.result.schools\[].enrolment** `number | null`

Students enrolled, excluding adult education; null for private or when suppressed.

**data.result.schools\[].teachers\_fte** `number | null`

Full-time-equivalent teachers; null when not stated.

**data.result.schools\[].student\_teacher\_ratio** `number | null`

Students per teacher; null when not stated.

**data.result.schools\[].latitude** `number | null`

Latitude of the school. `null` when the source gives no value.

**data.result.schools\[].longitude** `number | null`

Longitude of the school. `null` when the source gives no value.

**data.result.schools\[].distance\_km** `number | null`

Distance from the point in kilometres; null for a district search.

**data.result.schools\[].school\_year** `string | null`

The school year the row describes, for example 2024-2025. `null` when the source gives no value.

```bash cURL theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/lookup/place-schools \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "school_type": "public",
    "latitude": 42.2808,
    "longitude": -83.743,
    "limit": 1
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/place-schools", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "payment-signature": paymentProof,
  },
  body: JSON.stringify({
    "school_type": "public",
    "latitude": 42.2808,
    "longitude": -83.743,
    "limit": 1
  }),
});
```

```typescript SDK theme={null}
const result = await agent.tool('lookup/place-schools', {
  school_type: 'public',
  latitude: 42.2808,
  longitude: -83.743,
  limit: 1
});
console.log(result.result);
console.log(result.evidence);
```

```json Response (200) theme={null}
{
  "success": true,
  "data": {
    "request_id": "uuid",
    "receipt_id": "rcpt_...",
    "status": "completed",
    "tool": "place_schools",
    "result": {
      "school_type": "public",
      "total": 6,
      "more": true,
      "schools": [
        {
          "id": "260282004033",
          "name": "Community High School",
          "district_id": "2602820",
          "district_name": "Ann Arbor Public Schools",
          "address": "401 N DIVISION ST",
          "city": "ANN ARBOR",
          "state": "MI",
          "zip_code": "48104",
          "county": "Washtenaw County",
          "phone": "(734) 994-2021",
          "level": "High",
          "kind": "Regular School",
          "charter": false,
          "virtual": "Supplemental Virtual",
          "lowest_grade": "09",
          "highest_grade": "12",
          "status": "Open",
          "enrolment": 513,
          "teachers_fte": 34,
          "student_teacher_ratio": 15.09,
          "latitude": 42.2839,
          "longitude": -83.7443,
          "distance_km": 0.36,
          "school_year": "2024-2025"
        }
      ]
    },
    "evidence": {
      "source": "US National Center for Education Statistics",
      "source_kind": "public",
      "retrieved_at": "2026-10-26T12:00:00.000Z",
      "calls": [
        {
          "retrieved_at": "2026-10-26T12:00:00.000Z"
        }
      ],
      "as_of": null
    }
  }
}
```

> [!NOTE]
>
> See [Pricing](https://docs.oneshotagent.com/pricing.md) for this tool's price. A wallet (x402) call receives it in the 402 quote before anything is charged; a call paid from prepaid credits is charged when the API accepts the request and answers `200`.

## Notes

* Give `school_type` and either a point (`latitude`, `longitude`, with `radius_km` 0.5 to 10, default 2) or a public `district_id` (the seven-digit NCES district id); private schools have no district.
* Private rows carry no enrolment, phone, district, level, kind or status: the source layer does not publish them.
* `total` counts the schools the source returned, at most 2,000; `more` is true when more than `limit` were returned or the source held more than 2,000.
* Enrolment, teachers and ratio are null when the source marks them missing, not applicable or suppressed. Each row carries its school year.
* A point or district with no school gives `total: 0` and an empty list.
* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.