API REFERENCE

Search

On this page

GET/api/spotify/search

Search for artists, albums, tracks, and playlists using the Spotify API. This endpoint is a proxy to the official Spotify Search API.

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/spotify/search?q=YOUR_Q&type=YOUR_TYPE' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Query parameters

qstringrequired

The search query keywords and optional field filters

typestringrequired

A comma-separated list of item types to search across: album, artist, playlist, track, show, episode, audiobook

marketstring

An ISO 3166-1 alpha-2 country code or 'from_token'

limitinteger

Maximum number of results to return (default: 20, min: 1, max: 50)

Default: 20

offsetinteger

The index of the first result to return (default: 0, max: 10000)

Default: 0

Responses

200Search results retrieved successfully

application/json

artistsobject

Search results for artists (if type includes artist)

Properties

hrefstring

A link to the Web API endpoint returning the full result

itemsarray<SpotifyArtistObject>

List of artist objects

Item properties

external_urlsobject

Properties

spotifystring

The Spotify URL for the object

followersobject

Properties

hrefstringnullable

This will always be set to null

totalinteger

The total number of followers

genresarray<string>

A list of the genres the artist is associated with

Item properties

string

hrefstring

A link to the Web API endpoint providing full details

idstring

The Spotify ID for the artist

imagesarray<SpotifyImage>

Images of the artist in various sizes

Item properties

urlstring

The source URL of the image

heightintegernullable

The image height in pixels

widthintegernullable

The image width in pixels

namestring

The name of the artist

popularityinteger

The popularity of the artist (0-100)

typestring · enum

The object type, always 'artist'

Values: "artist"

uristring

The Spotify URI for the artist

limitinteger

The maximum number of items in the response

nextstringnullable

URL to the next page of items

offsetinteger

The offset of the items returned

previousstringnullable

URL to the previous page of items

totalinteger

The total number of items available

albumsobject

Search results for albums (if type includes album)

tracksobject

Search results for tracks (if type includes track)

playlistsobject

Search results for playlists (if type includes playlist)

400Bad request - missing required parameters

application/json

errorobject

Error details

Properties

statusinteger

HTTP status code

messagestring

Error message

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download social.json

View operation source

json

{
  "description": "Search for artists, albums, tracks, and playlists using the Spotify API. This endpoint is a proxy to the official Spotify Search API.",
  "parameters": [
    {
      "name": "q",
      "in": "query",
      "description": "The search query keywords and optional field filters",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "type",
      "in": "query",
      "description": "A comma-separated list of item types to search across: album, artist, playlist, track, show, episode, audiobook",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "market",
      "in": "query",
      "description": "An ISO 3166-1 alpha-2 country code or 'from_token'",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "limit",
      "in": "query",
      "description": "Maximum number of results to return (default: 20, min: 1, max: 50)",
      "required": false,
      "schema": {
        "type": "integer",
        "default": 20,
        "minimum": 1,
        "maximum": 50
      }
    },
    {
      "name": "offset",
      "in": "query",
      "description": "The index of the first result to return (default: 0, max: 10000)",
      "required": false,
      "schema": {
        "type": "integer",
        "default": 0,
        "maximum": 10000
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Search results retrieved successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SpotifySearchResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - missing required parameters",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SpotifyErrorResponse"
          }
        }
      }
    }
  }
}