Your audience.
Their next coach.

You are adding TeachMe.To coach discovery to my product.

Goal: my users find coaches inside my product, then book and pay on TeachMe.To. I earn attributed booking revenue. I never recruit coaches or run lessons.

## API contract

Base URL: https://api.teachme.to/v1/partner
Endpoint: GET /listings
Auth header: Authorization: Bearer <TEACHMETO_PARTNER_API_KEY>
Scope: listings:read

Call this API only from a server. Read the key from an environment variable. Never put the key in browser JavaScript, a mobile binary, a public repository, or logs. Never send the key to the browser in a server-rendered payload.

Query parameters for every request:
- skill: required string, for example tennis, golf, or pickleball
- modality: required, either online or in_person
- limit: optional integer from 1 to 50, defaults to 20
- cursor: optional string, use pagination.nextCursor from the previous page

Extra required parameters when modality is in_person:
- country: US or CA
- latitude: number from -85 to 85
- longitude: number from -180 to 180
- radiusMiles: number from 1 to 100

Online coaching is available worldwide. Local coaching is limited to the United States and Canada. Reject an in_person search outside those two countries before you call the API.

Example online request:
curl 'https://api.teachme.to/v1/partner/listings?skill=tennis&modality=online&limit=20' -H "Authorization: Bearer $TEACHMETO_PARTNER_API_KEY"

Example local request:
curl 'https://api.teachme.to/v1/partner/listings?skill=tennis&modality=in_person&country=US&latitude=32.7157&longitude=-117.1611&radiusMiles=25&limit=20' -H "Authorization: Bearer $TEACHMETO_PARTNER_API_KEY"

## Response shape

A 200 response returns this JSON:
{
  "data": [
    {
      "id": "listing_01",
      "name": "Jordan",
      "avatarUrl": "https://media.teachme.to/example.webp",
      "bio": "Patient tennis coach for beginners and returning players.",
      "skill": "tennis",
      "modality": "online",
      "rating": 4.9,
      "reviewCount": 82,
      "lessonsCount": 340,
      "startingPrice": { "amount": 65, "currency": "USD" },
      "locations": [],
      "bookingUrl": "https://teachme.to/listings/tennis/jordan?utm_medium=partner_api&utm_source=your-partner-ref&ref=your-partner-ref&online=true"
    }
  ],
  "pagination": { "limit": 20, "nextCursor": null }
}

The fields above are the complete public surface. The API never returns coach contact details, precise coordinates, calendars, meeting links, payout rates, or internal marketplace fields. Do not model or request those fields.

avatarUrl and bio can be null. locations is empty for online listings. Handle both cases in the UI.

## Errors and limits

- 400 with code INVALID_REQUEST: your query failed validation. Read the errors array.
- 400 with code INVALID_CURSOR: discard the cursor and restart pagination. Restart whenever filters, page size, or credentials change.
- 401 with code UNAUTHORIZED: the key is missing, wrong, or lacks listings:read.
- 429 with code RATE_LIMITED: honor the Retry-After header. Read RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset on every response.
- 503 with code SERVICE_UNAVAILABLE: retry with exponential backoff and jitter.

Responses carry Cache-Control: private, no-store. Never store a response in a shared or public cache, such as a CDN.

## What to build

1. Write a typed server-side client for GET /listings. Add a request timeout. Retry 429 and 503 with exponential backoff.
2. Add a discovery surface that fits my product. Show name, avatar, bio, rating, review count, lessons count, starting price, and city for local coaches.
3. Add a search input for skill. Add a location input for local search. Geocode the location to latitude and longitude before you call the API.
4. Send every user to the returned bookingUrl to book and pay. Use the URL exactly as returned. Never rewrite it, strip its query parameters, or wrap it in a redirect that drops parameters. That URL carries my partner attribution and my revenue depends on it.
5. Paginate with pagination.nextCursor. Stop when nextCursor is null.
6. Render a clear empty state when data is empty.
7. Write tests for the client, the error paths, and the attribution rule that bookingUrl passes through unchanged.

## Before you start

Ask me for my TeachMe.To partner API key. Store it as TEACHMETO_PARTNER_API_KEY in server environment configuration. Tell me which files you plan to add or change, then wait for my approval.

If I do not have a key yet, tell me to apply at https://teachme.to/partners#apply.