API Documentation

Step 1: Get Your API Key

To start using the API, you need to generate an API key.

Click here to access the API key generation page.
Follow the instructions on the page to generate your unique API key.
Store this API key securely, as you will need it for every request.

Step 2: Making a POST Request

Endpoint:

https://song.speakinsongs.com/api/v1/songs

Required Headers

x-api-key: <add-api-key-here>

Request Body (Example)

{
  "words": ["hello", "world"]
}

NOTE 1: The words array CANNOT be empty. Must contain ONLY strings & limited to 200 elements.

NOTE 2: All punctuation is stripped from strings to provide the best matching results.

Example Request

Using `curl`:


curl -X POST https://song.speakinsongs.com/api/v1/songs \ 
     -H "Content-Type: application/json" \ 
     -H "x-api-key: <add-api-key-here>" \
     -d '{"words": ["hello", "world"]}'

API Response

The API returns an array of objects, where each object provides detailed information about a matched song. Below is the structure of the response:

input: The word you provided as input.
song_name: The title of the matched song.
spotify_song_id: The unique identifier for the song on Spotify.
spotify_song_urls: An object containing URLs for the song on Spotify, e.g.
- spotify: The direct link to the song.
artists: An array of objects, each representing an artist associated with the song. Each artist object contains:
- name: The artist's name.
- id: The artist's unique Spotify ID.
- uri: The Spotify URI for the artist.
- external_urls: Links to the artist's Spotify profile.
images: An array of objects, each representing a song-related image. Each image object includes:
- url: The URL of the image.
- height and width: Dimensions of the image.

NOTE: If a word cannot be matched to a song then the object will be returned with NULL values

Example Response

[
  {
    "input": "example-word",
    "song_name": "Example Song",
    "spotify_song_id": "exampleSongId123",
    "spotify_song_urls": {
      "spotify": "https://open.spotify.com/track/exampleSongId123"
    },
    "artists": [
      {
        "name": "Example Artist",
        "id": "exampleArtistId123",
        "uri": "spotify:artist:exampleArtistId123",
        "external_urls": {
          "spotify": "https://open.spotify.com/artist/exampleArtistId123"
        }
      }
    ],
    "images": [
      {
        "height": 640,
        "width": 640,
        "url": "https://example.com/image1.jpg"
      },
    ]
  }
]

The images array may contain multiple sizes of the same image, useful for responsive design. Use the spotify_song_urls and artists.external_urls fields to link directly to Spotify resources.