# Niche — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and retrieve data on K-12 schools and colleges from Niche.com, including rankings, report card grades, stats, and user reviews.

**Category:** Education | **Website:** [niche.com/](https://niche.com/) | **Docs:** [parse.bot/marketplace/d794b14b-4423-431f-9d6f-2960f6fba703/niche-com-api](https://parse.bot/marketplace/d794b14b-4423-431f-9d6f-2960f6fba703/niche-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/niche/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Autocomplete search

Autocomplete search for schools, districts, or places. Returns matching results with type, label, grade, and URL information. Results are sorted by relevance.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search query string (e.g. 'harvard', 'stanford'). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/niche/autocomplete-search \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

### Get k12 district overview

Get detailed overview of a K-12 school district by its slug. Returns report card grades, rankings, stats, tags, and contact information. The slug is derivable from the urlFragment field returned by autocomplete_search for SchoolDistrict type results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | District slug from the URL path, derivable from autocomplete_search urlFragment for SchoolDistrict results (e.g. 'shawnee-mission-school-district-ks'). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/niche/get-k12-district-overview \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"slug":"<string>"}'
```

### Get k12 school overview

Get detailed overview of a K-12 school by its slug. Returns report card grades, rankings, stats, tags, and contact information. The slug is obtainable from search_k12_schools results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | School slug from the URL path, obtainable from search_k12_schools results (e.g. 'the-hotchkiss-school-lakeville-ct'). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/niche/get-k12-school-overview \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"slug":"<string>"}'
```

### Get k12 school reviews

Get reviews for a K-12 school by its slug. Returns paginated user reviews with ratings and author information. Each review includes author type, body text, numeric rating, and date.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |
| `slug` | string | Yes | School slug from the URL path, obtainable from search_k12_schools results (e.g. 'the-hotchkiss-school-lakeville-ct'). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/niche/get-k12-school-reviews \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","slug":"<string>"}'
```

### Search colleges

Search for colleges ranked by Niche grade. Returns paginated results. Each result includes the college name, slug, URL, overall grade, and tagline.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/niche/search-colleges \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>"}'
```

### Search k12 schools

Search for K-12 schools with optional filters. Returns paginated results ranked by Niche grade. Supports filtering by school type and grade level. Each result includes the school name, slug, URL, overall grade, and tagline.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `grades` | string | No | Grade level filter. Accepted values: 'elementary', 'middle', 'high'. |
| `page` | integer | No | Page number for pagination. |
| `type` | string | No | School type filter. Accepted values: 'private', 'public', 'charter'. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/niche/search-k12-schools \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"grades":"<string>","page":"<integer>","type":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.