# SocialCrawl API: apple_music endpoints
# Base URL: https://www.socialcrawl.dev
# Auth: x-api-key header
# Full docs: https://www.socialcrawl.dev/docs/apple_music

## GET /v1/apple_music/search
Search Apple Music
Credit cost: 1 (standard)
Parameters:
- query (required): Search query.
- type (optional, string): Optional result kind such as song, album, or artist.
curl -G "https://www.socialcrawl.dev/v1/apple_music/search" \
  --data-urlencode "query=taylor swift" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/apple_music/artist
Get an Apple Music artist
Credit cost: 1 (standard)
Parameters:
- id (optional, string): Apple Music artist ID.
- url (optional, string): Apple Music artist URL.
- Constraint: one of id, url (at least one required)
curl -G "https://www.socialcrawl.dev/v1/apple_music/artist" \
  --data-urlencode "url=https://music.apple.com/us/artist/taylor-swift/159260351" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/apple_music/album
Get an Apple Music album
Credit cost: 1 (standard)
Parameters:
- id (optional, string): Apple Music album ID.
- url (optional, string): Apple Music album URL.
- Constraint: one of id, url (at least one required)
curl -G "https://www.socialcrawl.dev/v1/apple_music/album" \
  --data-urlencode "url=https://music.apple.com/us/album/red-taylors-version/1590368448" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/apple_music/track
Get an Apple Music track
Credit cost: 1 (standard)
Parameters:
- id (optional, string): Apple Music track ID.
- url (optional, string): Apple Music track URL.
- Constraint: one of id, url (at least one required)
curl -G "https://www.socialcrawl.dev/v1/apple_music/track" \
  --data-urlencode "url=https://music.apple.com/us/album/22-taylors-version/1590368448?i=1590368457" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/apple_music/charts
Get the Apple Music charts for a country
Credit cost: 1 (standard)
Parameters:
- country (optional, string): Country as an ISO 3166-1 alpha-2 code, in any case (`us`, `DE`, `kr`). Apple Music publishes a chart for most countries where it is sold; one it does not is rejected with a free 400. `uk` is read as `gb`. Defaults to `us`.
- type (optional, enum: songs | albums | music-videos | playlists): Which chart: `songs` (the default), `albums`, `music-videos` or `playlists`.
- limit (optional, integer): How many chart positions to return, from the top, 1 to 100. Defaults to 50.
- since (optional, string): Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.
- until (optional, string): Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.
Worth sending:
- country=de: Results for one country.
curl -G "https://www.socialcrawl.dev/v1/apple_music/charts" \
  --data-urlencode "country=de" \
  -H "x-api-key: YOUR_API_KEY"