Official Ruby Gem to access the Hark API
Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
test
.gitignore
Gemfile
Gemfile.lock
README.md
Rakefile
hark.gemspec

README.md

Hark API

A Ruby Gem to access the hark.com API

About Hark

hark.com is a site that publishes movie quote sound bites and still images. This gem is used to access these sounds 📣 , still images, and other information in a programmatic fashion.

Reference

Pure HTTP Example

The Hark API is accessed through a HTTP GET focused REST interface currently supporting JSON and JSONP formats. The API is currently version 1.0 and is only accessible over HTTPS. The token to access the API is submitted as a HTTP header with the name X-HarkToken.

JSON Access

curl --verbose -H "X-HarkToken: a-token" "https://api.hark.com/1.0/clips/jxxcfhxywx.json"

JSONP Access

The value of callback is the variable name that is returned wrapping the result JSON.

curl --verbose -H "X-HarkToken: a-token" "https://api.hark.com/1.0/clips/jxxcfhxywx.json?callback=wrapper"

Formatting

API Information

All results return information about the request and its results.

  • version - API Version.
  • when - When these results returned.
  • what - The kind of object requested, clip, clips, collection, collections, etc.
  • message - A message about the request.
  • status - The HTTP status given with the result.

Error results

Missing query parameters

HTTP Status 400. Parameter(s) for the query were missing.

{
  "collections": [

  ],
  "api": {
    "version": "1.0.1",
    "when": "Tue Nov 01 05:39:41 UTC 2011",
    "what": "collections",
    "message": "missing keywords query",
    "status": 400
  }
}

Authorization Failure

HTTP Status 401. The API token given was not authorized.

{
  "api": {
    "version": "1.0.1",
    "when": "Tue Nov 01 05:34:41 UTC 2011",
    "what": "clips",
    "message": "Unauthorized",
    "status": 401
  },
  "clip": {
  }
}

Not Found

HTTP Status 404. The resource requested was not found.

{
  "api": {
    "version": "1.0.1",
    "when": "Tue Nov 01 05:48:05 UTC 2011",
    "what": "clip",
    "message": "Not Found",
    "status": 404
  },
  "clip": {
  }
}

Unprocessable Entity

HTTP Status 422. The URI of the query did not map to any resources currently presented by the API.

{
  "api": {
    "version": "1.0.1",
    "when": "Tue Nov 01 05:48:54 UTC 2011",
    "what": "noob",
    "message": "Unprocessable Entity",
    "status": 422
  }
}

Clip JSON

Request

curl -H "X-HarkToken: a-token" "https://api.hark.com/1.0/clips/jxxcfhxywx.json"

Attributes

  • audio_url - A CDN URL to the audio portion of the clip. URL will have expiry information attached to it, and will expire in 60 minutes from the time of the request.
  • canonical_url - Unique URL of the clip.
  • description - A description of the clip.
  • duration - The clip's duration in seconds.
  • image_urls - An array of images associated with the clip.
  • name - The name of the clip.
  • pid - Unique identifier of the clip.
  • quote - A distinctive quote from the clip.
  • short_url - A bit.ly shortened URL to the clip.

Example

{
  "api": {
    "version": "1.0.1",
    "when": "Tue Nov 01 05:58:46 UTC 2011",
    "what": "clip",
    "message": "OK",
    "status": 200
  },
  "clip": {
    "audio_url": "*** A VALID EXPIRING CDN AUDIO URL ***",
    "canonical_url": "http://hark.com/clips/jxxcfhxywx-i-have-a-dream-today",
    "description": "Martin Luther King Jr. gives his I Have a Dream Speech.",
    "duration": 2,
    "image_urls": [
      "http://cdn2.hark.com/images/000/000/224/224/martin-luther-king-jr_large.jpg"
    ],
    "name": "I have a dream today",
    "pid": "jxxcfhxywx",
    "quote": "\"I have a dream today!\"",
    "short_url": "http://bit.ly/fPKQmO"
  }
}

Clips Search JSON

Request

curl -H "X-HarkToken: a-token" "https://api.hark.com/1.0/clips/search?keywords=a+search+phrase"

Attributes

  • clips - An array of clips specified above.

Example

{
  "clips": [
    { SEE CLIP DESCRIPTION ABOVE },
    { SEE CLIP DESCRIPTION ABOVE },
    { SEE CLIP DESCRIPTION ABOVE }
  ],
  "api": {
    "version": "1.0.1",
    "when": "Tue Nov 01 06:10:11 UTC 2011",
    "what": "clips",
    "message": "OK",
    "status": 200
  }
}

Collection JSON

Request

curl -H "X-HarkToken: a-token" "https://api.hark.com/1.0/collections/nfngpynlrd.json"

Attributes

  • canonical_url - Unique URL of the collection.
  • clip_pids - Array of clip pids belonging to the collection.
  • description - A description of the collection.
  • image_urls - Array of images belonging to the collection.
  • name - The name of the collection.
  • pid - Unique identifier of the collection.
  • short_url - A bit.ly shortened URL to the collection.

Example

{
  "api": {
    "version": "1.0.1",
    "when": "Tue Nov 01 06:21:28 UTC 2011",
    "what": "collection",
    "message": "OK",
    "status": 200
  },
  "collection": {
    "canonical_url": "http://hark.com/collections/nfngpynlrd-the-godfather",
    "clip_pids": [
      "jtpmzgfktg",
      "mdgnglbypn",
      "vlbldnhdlc",
      "kmbksnnsry"
    ],
    "description": "The Godfather is a 1972 American crime drama film based on the 1969 novel ...",
    "image_urls": [
      "http://cdn0.hark.com/images/000/001/572/1572/the-godfather_large.jpg",
      "http://cdn2.hark.com/images/000/046/310/46310/the-godfather_large.jpg",
      "http://cdn2.hark.com/images/000/425/462/425462/the-godfather_large.jpg"
    ],
    "name": "The Godfather",
    "pid": "nfngpynlrd",
    "short_url": "http://hark.com/collections/nfngpynlrd-the-godfather"
  }
}

Collections Search JSON

Request

curl -H "X-HarkToken: a-token" "https://api.hark.com/1.0/collections/search?keywords=a+search+phrase"

Attributes

  • collections - An array of collections specified above.

Example

{
  "collections": [
    { SEE COLLECTION DESCRIPTION ABOVE },
    { SEE COLLECTION DESCRIPTION ABOVE },
    { SEE COLLECTION DESCRIPTION ABOVE }
  ],
  "api": {
    "version": "1.0.1",
    "when": "Tue Nov 01 06:10:11 UTC 2011",
    "what": "collections",
    "message": "OK",
    "status": 200
  }
}

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! NOTE !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! !! The Ruby implementation is a work in progress. The interface will likely !! !! change as well as be expanded upon. !! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Ruby Examples

Configure the API and fetch a clip.

require 'hark'

Hark::API.configure do |config|
  config.api_key = 'the-key'
end

Hark::API.clip('jxxcfhxywx') # returns JSON