# Apple Music (/docs/apple_music)

Apple Music search, artists, albums, and tracks through one unified API

Apple Music catalog reads: search by keyword, then fetch an artist, album or track by id or URL. Every endpoint is a `GET` and costs 1 credit.

Base URL: `/v1/apple_music/...`

## Quickstart

### 1. Search the catalog

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/apple_music/search?query=taylor%20swift&type=song" \
  -H "x-api-key: YOUR_API_KEY"
```

### 2. Fetch the full record

`artist`, `album` and `track` each take an `id` or a `url`. Supply exactly one.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/apple_music/artist?url=https://music.apple.com/us/artist/taylor-swift/159260351" \
  -H "x-api-key: YOUR_API_KEY"
```

## Search

| Endpoint                     | Credits | What it returns               | Key parameters                                                      |
| ---------------------------- | ------- | ----------------------------- | ------------------------------------------------------------------- |
| `GET /v1/apple_music/search` | 1       | Catalog matches for a keyword | `query`, `type` (a result kind such as `song`, `album` or `artist`) |

Search is the keyword entry point. It is the only endpoint here that does not need an id.

## Catalog records

| Endpoint                     | Credits | What it returns                     | Key parameters |
| ---------------------------- | ------- | ----------------------------------- | -------------- |
| `GET /v1/apple_music/artist` | 1       | One performer's full catalog record | `id` or `url`  |
| `GET /v1/apple_music/album`  | 1       | One record with its track list      | `id` or `url`  |
| `GET /v1/apple_music/track`  | 1       | One song                            | `id` or `url`  |

The id is the numeric segment at the end of any music.apple.com link.

## All endpoints

## Platform notes

- **`artist`, `album` and `track` each accept `id` or `url`.** Supply exactly one. Sending neither is a `400` before billing.
- **Search returns a single page.** There is no cursor and no offset on this platform.
- Where an endpoint supports a computed field and the required source inputs are present, the response carries it. See [Computed fields](/docs/computed-fields.md) for formulas, clamping rules, and null semantics. Where an endpoint supports them, list rows also carry judged labels (`computed.labels`, `computed.relevance`) by default at no extra credits; see [Labels](/docs/labels.md).
- All endpoints use `GET` with query parameters, and responses follow the unified SocialCrawl schema.

## Next steps

- [Spotify](/docs/spotify.md): The same catalog reads, plus podcast shows and episodes.
- [Computed fields](/docs/computed-fields.md): Formulas, clamping rules, and null semantics.
- [Credits](/docs/credits.md): How billing, caching, and refunds work.