> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topyappers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Songs Data

> Access trending songs data with various actions. Use the `action` parameter to specify what data to retrieve.



## OpenAPI

````yaml GET /api/v1/songs
openapi: 3.1.0
info:
  title: Songs API
  description: >-
    API for accessing trending songs data, rankings, and chart history across
    different countries and time periods
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.topyappers.com
security:
  - apiKeyAuth: []
paths:
  /api/v1/songs:
    get:
      summary: Songs API
      description: >-
        Access trending songs data with various actions. Use the `action`
        parameter to specify what data to retrieve.
      parameters:
        - name: action
          in: query
          required: true
          description: The action to perform
          schema:
            type: string
            enum:
              - countries
              - weeks
              - date-ranges
              - rankings
              - global
              - new-entries
              - search
              - song-history
              - compare
          example: rankings
        - name: country
          in: query
          description: 'Country code (required for: rankings, new-entries, compare)'
          schema:
            type: string
          example: US
        - name: country_code
          in: query
          description: 'Country code (used for: weeks, song-history)'
          schema:
            type: string
          example: US
        - name: week
          in: query
          description: Week in ISO format (YYYY-Www) for rankings and global
          schema:
            type: string
          example: 2026-W04
        - name: week1
          in: query
          description: 'First week for comparison (required for: compare)'
          schema:
            type: string
          example: 2026-W03
        - name: week2
          in: query
          description: 'Second week for comparison (required for: compare)'
          schema:
            type: string
          example: 2026-W04
        - name: song_id
          in: query
          description: 'Song ID (required for: song-history)'
          schema:
            type: string
          example: '123456'
        - name: q
          in: query
          description: 'Search query (used for: search)'
          schema:
            type: string
          example: trending
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SongsResponse'
        '400':
          description: Bad request - missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceeded'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SongsResponse:
      type: object
      properties:
        message:
          type: string
          example: OK
        action:
          type: string
          description: The action that was performed
          example: rankings
        credits_used:
          type: integer
          description: Number of credits consumed by this request
          example: 10
        response:
          type: object
          description: The response data (varies by action)
      required:
        - message
        - action
        - credits_used
        - response
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
    RateLimitExceeded:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: Too many requests
        retryAfter:
          type: integer
          description: Seconds to wait before retrying
          example: 60
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-ty-api-key
      description: API key for TopYappers API authentication

````