Search Guide

The search guide covers the following:

  • Creating a search
  • Paging through search results

Prerequisites

You have run through the Getting Started Guide and have an access token to use for the following API requests.

Creating a search.

There are a number of supported query parameters.

parameter description
type (Required) The type of entity to search. Must be one of 'series' or 'episode'
q (Required) your search terms
size The number of results to return per page of results
start The index of the results to start at

To submit a search, perform a GET or POST on /search.

$ curl -H 'Authorization: Bearer TOKEN' 'https://api.wurl.com/api/search?q=funny&type=series'

The response's properties section will contain some meta-data about the search and the entities collection will be the search hits:

{
  "rel":["properties:http://api.wurl.com/schemas/search_response.json"],
  "class":["search"],
  "properties":{"searchTerms":"funny","hits":139,"start":0},

  "entities":[ 
      // A list of series entities) 
      {
        "rel":["urn:x-resource:schema:https://wurl-api-qa.herokuapp.com/schemas/series.json"],
        "class":["series"],
        "title":"Comedy Time Dir",
        "properties": {
          "id":371356,
          "description":"Description of this very funny show....",
          "channelsRank":82.7534294465409,
          "pubDate":"2013-09-13T16:35:43Z",
          "thumbnails":{
            "default":{
              "url":"http://i1.ytimg.com/i/Ug9Iv_KnZwTulS0cEi_mJQ/1.jpg?v=8badd5"
            }
          }
        },
        "totalEpisodes":128,
        "matchesApp":true,
        "link":"http://www.youtube.com/channel/UCUg9Iv_KnZwTulS0cEi_mJQ/videos"
      },
  ],

  "links":[
    {"rel":["self"],"href":"https://api.wurl.com/api/search?q=funny"},
    {"rel":["next"],"href":"https://api.wurl.com/api/search?q=funny&start=10"}
    // 'prev' link may also be here
  ]

} 

Paging through a search

Note the "links" section. This is an array of related links you can use. Like all paginated responses, "next" and "prev" may be here for you to continue paging through the search results.

Query Syntax

When searching, all the terms in your query are individual terms that are ANDed together. To search for a specific multi-word query (eg: star wars) you can enclose search terms in double quotes.

  • q="star wars" matches the exact term "star wars"

You can also use the boolean operators + (AND), | (OR), and - (NOT). If you separate search terms with + or a space, all of the search terms are ANDed together. You can use the | (OR) operator to separate terms when you want either the preceding term(s) or the following term(s). To exclude a particular term, prefix the term with the - (NOT) operator. The NOT operator only applies to individual terms.

For example:

  • q=star+wars matches star and wars.
  • q=star|wars matches either star or wars.
  • q=star|wars-trek matches either star or wars but does not contain trek.

You can use the * (asterisk) wildcard operator to perform some limited wildcard matching. The * operator only applies to individual terms. When you append the * operator to a string, the string is treated as a prefix.

  • q=star* matches any words that start with 'star' (star, start, etc...)
NOTE: The samples ignored URL (percent) encoding for clarity.

Search Guide

The search guide covers the following:

Prerequisites

You have run through the Getting Started Guide and have an access token to use for the following API requests.

Creating a search.

There are a number of supported query parameters.

parameter description
type (Required) The type of entity to search. Must be one of 'series' or 'episode'
q (Required) your search terms
size The number of results to return per page of results
start The index of the results to start at

To submit a search, perform a GET or POST on /search.

$ curl -H 'Authorization: Bearer TOKEN' 'https://api.wurl.com/api/search?q=funny&type=series'

The response's properties section will contain some meta-data about the search and the entities collection will be the search hits:

{
  "rel":["properties:http://api.wurl.com/schemas/search_response.json"],
  "class":["search"],
  "properties":{"searchTerms":"funny","hits":139,"start":0},

  "entities":[ 
      // A list of series entities) 
      {
        "rel":["urn:x-resource:schema:https://wurl-api-qa.herokuapp.com/schemas/series.json"],
        "class":["series"],
        "title":"Comedy Time Dir",
        "properties": {
          "id":371356,
          "description":"Description of this very funny show....",
          "channelsRank":82.7534294465409,
          "pubDate":"2013-09-13T16:35:43Z",
          "thumbnails":{
            "default":{
              "url":"http://i1.ytimg.com/i/Ug9Iv_KnZwTulS0cEi_mJQ/1.jpg?v=8badd5"
            }
          }
        },
        "totalEpisodes":128,
        "matchesApp":true,
        "link":"http://www.youtube.com/channel/UCUg9Iv_KnZwTulS0cEi_mJQ/videos"
      },
  ],

  "links":[
    {"rel":["self"],"href":"https://api.wurl.com/api/search?q=funny"},
    {"rel":["next"],"href":"https://api.wurl.com/api/search?q=funny&start=10"}
    // 'prev' link may also be here
  ]

} 

Paging through a search

Note the "links" section. This is an array of related links you can use. Like all paginated responses, "next" and "prev" may be here for you to continue paging through the search results.

Query Syntax

When searching, all the terms in your query are individual terms that are ANDed together. To search for a specific multi-word query (eg: star wars) you can enclose search terms in double quotes.

You can also use the boolean operators + (AND), | (OR), and - (NOT). If you separate search terms with + or a space, all of the search terms are ANDed together. You can use the | (OR) operator to separate terms when you want either the preceding term(s) or the following term(s). To exclude a particular term, prefix the term with the - (NOT) operator. The NOT operator only applies to individual terms.

For example:

You can use the * (asterisk) wildcard operator to perform some limited wildcard matching. The * operator only applies to individual terms. When you append the * operator to a string, the string is treated as a prefix.

NOTE: The samples ignored URL (percent) encoding for clarity.