واجهة برمجة الموسيقى من Popnable

#What this API solves

One POST endpoint that proxies Popnable API and returns normalized JSON for search, trends, songs, artists, charts and YouTube videos. Use it when you need consistent data structures across multiple upstream calls, stable field names, predictable errors, and idempotent behavior suitable for caching.

#Endpoint & call model

#POST https://api.yeb.to/v1/music-popnable

• Best for: Unified access to Popnable data with opinionated normalization.
• How it works: You send an action plus its parameters; we call the corresponding Popnable v2 method and normalize the response.
• Idempotent: Same input → same output; safe for caching and retries.
• Billing: Each request costs a fixed amount of credits (see chip above), regardless of the action.

#Quick start

# 1) Search (songs/artists) by keyword
curl -X POST "https://api.yeb.to/v1/music-popnable" \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "YOUR_KEY", "action": "search", "keyword": "preslava" }'

# 2) Songs by trend (country/region) for a specific day
curl -X POST "https://api.yeb.to/v1/music-popnable" \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "YOUR_KEY", "action": "get-songs-by-trend",
        "trend": "35", "day": "2025-01-05", "stats": "yes", "charts": "daily,weekly" }'

# 3) YouTube videos (normalized + optional charts/daily breakdown)
curl -X POST "https://api.yeb.to/v1/music-popnable" \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "YOUR_KEY", "action": "get-videos",
        "yt_codes": "AbCdE123,ZXCV987", "charts": "daily,weekly",
        "dailyStats": "yes", "day": "2025-01-05" }'

#Common parameters (used by all actions)

#Actions explained (what each one solves)

#action=search

Solves: quick lookup when you have a name fragment and need likely candidates (songs/artists).

{
  "api_key": "YOUR_KEY",
  "action" : "search",
  "keyword": "preslava"
}

{
  "data": [
    { "id": 123, "song_name": "Some Song", "trend_id": 35, "singers": [ { "singer_id": 777, "artist_name": "Preslava" } ] }
  ],
  "meta": { "provider": "popnable", "upstream_response_code": 200, "endpoint": "search" }
}

#action=get-trends

Solves: obtain available trend IDs (countries/regions) to drive UI pickers or scheduled fetches.

#action=get-songs

Solves: fetch details for known song IDs (e.g., to refresh a small cached set, or hydrate UI cards).

#action=get-songs-by-trend

Solves: build daily feeds per country/region for discovery, newsletters, or archives.

#action=get-artists

Solves: hydrate artist cards and detail pages from known IDs.

#action=get-artist-by-trend

Solves: discover artists by country/region for a given day; useful for editorial picks.

#Charts — daily/weekly/monthly/artist

Solves: pull historical chart snapshots for analytics, leaderboards, or recap posts.

#action=get-videos

Solves: normalize YouTube video data and optionally enrich with chart context and daily breakdowns.

#Reading & acting on responses

{
  "data": [
    {
      "id": 123,
      "song_name": "Some Song",
      "day_released": "2025-01-05 12:34:56",
      "trend": "Bulgaria",
      "trend_flag": "https://popnable.com/images/flags/circle/bg.svg",
      "trend_id": 35,
      "singers": [ { "singer_id": 777, "artist_name": "Preslava" } ],
      "videos":   [ { "yt_code": "AbCdE123" } ]
    }
  ],
  "meta": {
    "provider": "popnable",
    "upstream_response_code": 200,
    "upstream_error_number": null,
    "endpoint": "search"
  }
}

• data — normalized records. Use directly in UI and storage.
• meta.provider — popnable for transparency/debug.
• meta.upstream_response_code — HTTP-equivalent status from upstream.
• meta.endpoint — which upstream path we called (e.g., songs/by-trend).

#Typical errors & how to fix

{ "error": "Missing \"action\" parameter", "code": 422 }

{ "error": "Missing or empty \"ids\"", "code": 422 }

{ "error": "Popnable: Access Denied.", "code": 403 }

• 422 missing/invalid: Ensure required params for the chosen action are present and non-empty.
• 401 invalid key: Rotate your YEB key; call only from server/edge.
• 502 availability: Upstream temporarily unavailable; retry with backoff.
• 403 upstream denial: Access rules on provider side; validate your upstream configuration and inputs.

#Troubleshooting & field notes

1. Dates: All day params are YYYY-MM-DD. Keep a single timezone (prefer UTC) in your app.
2. Batching: For bulk imports, cap at ≤100 rps and reuse connections. Cache idempotent requests by full payload hash.
3. Partial enrichment: Use stats/charts/dailyStats only when needed to keep latency and cost predictable.
4. Stability: Field names are normalized; upstream changes are absorbed where possible and reflected in the Changelog below.

#API Changelog (latest changes)