API: Search

In this page

About the Search API

The Search API is optimized to help you find the specific item you’re looking for (e.g., a specific episode, a specific show, etc.). Think of it the way you would when performing a Google search.

Ranking Search Results

Results are sorted according to the best match. Multiple factors are combined to boost the most relevant item to the top of the list of results.

Entrypoint and Parameters

The entrypoint is /v2/search and the list of supported parameters is here below. The API response is paginated.

Parameter Required Type Description
q Yes String The query, keyword that each result matches
type Yes String The kind of entity returned. Supported values are episodes and shows
limit No Number Number of items returned in each page

Searching Shows

Find shows matching the input query.

GET /v2/search?type=shows&q=rock

This method returns a paginated response of Shows, with up to 100 results per page.

Example

curl 'https://api.spreaker.com/v2/search?type=shows&q=rock&limit=2'
{
  "response": {
    "items": [
      {
        "show_id": 1546314,
        "title": "The Rocketship Podcast : Startups | Entrepreneurship | Growth",
        "site_url": "https://www.spreaker.com/show/the-rocketship-podcast-startups-entrepre",
        "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/09074df5d400251110379549cb7c6a31.jpg",
        "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/09074df5d400251110379549cb7c6a31.jpg",
        "author_id": 8414694
      },
      {
        "show_id": 1570902,
        "title": "War on the Rocks",
        "site_url": "https://www.spreaker.com/show/war-on-the-rocks",
        "image_url": null,
        "image_original_url": null,
        "author_id": 8464333
      }
    ],
    "next_url": "https://api.spreaker.com/v2/search?q=rock&type=shows&offset=2&limit=2"
  }
}

Searching Shows by Author

Find shows, created by the USER-ID, matching the input query.

GET /v2/search/users/USER-ID?type=shows&q=rock

This method returns a paginated response of Shows, with up to 100 results per page.

Parameter Type Description
filter String Filters episodes by listenable or editable (defaults to listenable). If you specify filter=editable the request must be authenticated with USER-ID credentials.

Example

curl 'https://api.spreaker.com/v2/search/users/1?type=shows&q=rock&limit=2'
{
  "response": {
    "items": [{
      "show_id": 1546314,
      "title": "The Rocketship Podcast : Startups | Entrepreneurship | Growth",
      "site_url": "https://www.spreaker.com/show/the-rocketship-podcast-startups-entrepre",
      "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/09074df5d400251110379549cb7c6a31.jpg",
      "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/09074df5d400251110379549cb7c6a31.jpg",
      "author_id": 1
    },
    {
      "show_id": 1570902,
      "title": "War on the Rocks",
      "site_url": "https://www.spreaker.com/show/war-on-the-rocks",
      "image_url": null,
      "image_original_url": null,
      "author_id": 1
    }],
    "next_url": "https://api.spreaker.com/v2/search/users/1?q=rock&type=shows&filter=listenable&offset=2&limit=2"
  }
}

Searching Episodes

Find episodes matching the input query.

GET /v2/search?type=episodes&q=rock

This method returns a paginated response of Episodes, with up to 100 results per page.

Example

curl 'https://api.spreaker.com/v2/search?type=episodes&q=rock&limit=2'
{
  "response": {
    "items": [
      {
        "episode_id": 7780917,
        "type": "RECORDED",
        "title": "What Is Rock Nation Inc.?",
        "duration": 2371450,
        "show_id": 463349,
        "author_id": 4736290,
        "site_url": "https://www.spreaker.com/episode/7780917",
        "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/c83cef1bc698a5875be2d60b0281dea6.jpg",
        "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/c83cef1bc698a5875be2d60b0281dea6.jpg",
        "published_at": "2016-02-13 17:51:02",
        "download_enabled": true,
        "show": {
          "show_id": 463349,
          "title": "The Classic Metal Show",
          "site_url": "https://www.spreaker.com/show/the_classic_metal_show",
          "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/20faf34a18541d7fda375d11ee9864a8.jpg",
          "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/20faf34a18541d7fda375d11ee9864a8.jpg",
          "author_id": 4736290
        }
      },
      {
        "episode_id": 7685699,
        "type": "RECORDED",
        "title": "Chris Gets A Visit From Rockin' Randy",
        "duration": 1433610,
        "show_id": 463349,
        "author_id": 4736290,
        "site_url": "https://www.spreaker.com/episode/7685699",
        "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/c83cef1bc698a5875be2d60b0281dea6.jpg",
        "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/c83cef1bc698a5875be2d60b0281dea6.jpg",
        "published_at": "2016-02-01 08:00:12",
        "download_enabled": true,
        "show": {
          "show_id": 463349,
          "title": "The Classic Metal Show",
          "site_url": "https://www.spreaker.com/show/the_classic_metal_show",
          "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/20faf34a18541d7fda375d11ee9864a8.jpg",
          "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/20faf34a18541d7fda375d11ee9864a8.jpg",
          "author_id": 4736290
        }
      }
    ],
    "next_url": "https://api.spreaker.com/v2/search?q=rock&type=episodes&offset=2&limit=2"
  }
}

Searching Episodes by Author

Find episodes, created by the USER-ID, matching the input query.

GET /v2/search/users/USER-ID?type=episodes&q=rock

This method returns a paginated response of Episodes, with up to 100 results per page.

Parameter Type Description
filter String Filters episodes by listenable or editable (defaults to listenable). If you specify filter=editable the request must be authenticated with USER-ID credentials.

Example

curl 'https://api.spreaker.com/v2/search/users/1?type=episodes&q=test&limit=2'
{
  "response": {
    "items": [{
      "episode_id": 1033,
      "type": "RECORDED",
      "title": "Test_me_New_LIVE",
      "duration": 63138,
      "show_id": 220,
      "author_id": 1,
      "site_url": "https://www.spreaker.com/episode/1033",
      "image_url": null,
      "image_original_url": null,
      "published_at": "2014-06-10 08:07:19",
      "download_enabled": true
    }, {
      "episode_id": 76186,
      "type": "RECORDED",
      "title": "Test",
      "duration": 28970,
      "show_id": 296,
      "author_id": 1,
      "site_url": "https://www.spreaker.com/episode/76186",
      "image_url": null,
      "image_original_url": null,
      "published_at": "2016-02-03 08:27:59",
      "download_enabled": false
    }],
    "next_url": "https://api.spreaker.com/v2/search/users/1?q=test&type=episodes&filter=listenable&offset=2&limit=2"
  }
}

Searching Episodes by Show

Find episodes belonging to a SHOW-ID, matching the input query.

GET /v2/search/shows/SHOW-ID?type=episodes&q=rock

This method returns a paginated response of Episodes, with up to 100 results per page.

Parameter Type Description
filter String Filters episodes by listenable or editable (defaults to listenable). If you specify filter=editable the request must be authenticated with SHOW-ID owner credentials.

Example

curl 'https://api.spreaker.com/v2/search/shows/1?type=episodes&q=test&limit=2'
{
  "response": {
    "items": [{
      "episode_id": 1033,
      "type": "RECORDED",
      "title": "Test_me_New_LIVE",
      "duration": 63138,
      "show_id": 1,
      "author_id": 1,
      "site_url": "https://www.spreaker.com/episode/1033",
      "image_url": null,
      "image_original_url": null,
      "published_at": "2014-06-10 08:07:19",
      "download_enabled": true
    }, {
      "episode_id": 76186,
      "type": "RECORDED",
      "title": "Test",
      "duration": 28970,
      "show_id": 1,
      "author_id": 1,
      "site_url": "https://www.spreaker.com/episode/76186",
      "image_url": null,
      "image_original_url": null,
      "published_at": "2016-02-03 08:27:59",
      "download_enabled": false
    }],
    "next_url": "https://api.spreaker.com/v2/search/shows/1?q=test&type=episodes&filter=listenable&offset=2&limit=2"
  }
}