Welcome to TalentOyster OCEAN

TalentOyster OCEAN is the API (programming interface) for the TalentOyster platform for third-party websites. If you are the owner of a website or website developer TalentOyster OCEAN lets you embed job search functionality and content from TalentOyster right into your website via a RESTful API. To put it simply, it's a quick way to add content and job searching capabilities to your website.

How it works
Application Keys
The Job Search API
The Connect News API
PHP Library

How it works

You can execute searches for jobs on TalentOyster from your own site by making calls to our API. These calls will return you XML content which you can then reformat/present as you like to the visitors of your site. Step by step the flow is as follows:

User clicks submit button of search form on your site
User search parameters are submitted to your site
Your site sends a request to OCEAN
TalentOyster OCEAN sends an XML format response to your site
Your site parses/formats XML response and sends display back to user
User sees live search results from a TalentOyster job search directly on your site

Application Keys

Before you can start using OCEAN you must have a key for your application. Application keys and access to the OCEAN API are currently both free of charge. You can request a key for your application here.

Once you have a key you can use the API to search jobs or retrieve some Connect content. If you are using PHP this process can be made easier by using our PHP Library.

The Job Search API

The Job Search API works by making a GET request, with parameters below, to the resource http://www.talentoyster.com/api/Jobs

Parameter Name	Required?	Data type/example
key	YES	The string/text value with your application key
count	NO	An integer value with the maximum number of jobs that match the search that should be returned. If not supplied the default value is 20. The maximum number of jobs you can request is 40, requests for more results will be capped at 40.
l	NO	URL encoded string of locations (cities) to search in
q	NO	URL encoded string of search keywords to use
out	NO	Specifies the format of the response. Use XML or RSS formats. If not supplied the default response type is XML.

Note: if you do not supply a valid application key with each request you will receive an HTTP 403 (unauthorized) error.

After making the request you will receive a response in either RSS (if you specifically requested) or an XML document with the following structure.

<!DOCTYPE talentoyster_response [

<!ELEMENT code (#PCDATA)>

<!ELEMENT content (total,job*)>

<!ELEMENT total (#PCDATA)>

<!ELEMENT job (url,title,postdate,company,city,latitude,longitude,summary)>

<!ELEMENT url (#PCDATA)>

<!ELEMENT title (#PCDATA)>

<!ELEMENT postdate (#PCDATA)>

<!ELEMENT company (#PCDATA)>

<!ELEMENT city (#PCDATA)>

<!ELEMENT latitude (#PCDATA)>

<!ELEMENT longitude (#PCDATA)>

<!ELEMENT summary (#PCDATA)>

]>

The code element will almost always return 200. Other code values indicate an error in processing your request. The count element will tell you how many jobs on TalentOyster in total matched the search criteria. The fields of job information are relatively self-explanatory, the latitude and longitude geo-coordinate fields are currently not populated but can be at your request.

Here you can find an example of an XML response from OCEAN.

The Connect News API

The Connect News API lets you pull abstracts of the latest Connect content into your site. It works by making a GET request, with parameters below, to the resource http://www.talentoyster.com/api/ConnectNews

Parameter Name	Required?	Data type/example
key	YES	The string/text value with your application key
count	NO	An integer value with the maximum number of news items for the requested category. If not supplied the default value is 5. The maximum number of news items you can request is 20, requests for more results will be capped at 20.
out	NO	Specifies the format of the response. Use XML or RSS formats. If not supplied the default response type is XML.
c	NO	An integer value specifying the category of content you wish to retrieve. There are four possible values for category and they are: 1 for "Guidy Talks", 6 for "Diversity and the Workplace", 7 for "Diversity News" and 8 for "Resources for Job Seekers". If a valid option for category is not specified the default is category 7 "Diversity News".

Note: if you do not supply a valid application key with each request you will receive an HTTP 403 (unauthorized) error.

After making the request you will receive a response in either RSS (if you specifically requested) or an XML document with the following structure.

<!DOCTYPE talentoyster_response [

<!ELEMENT code (#PCDATA)>

<!ELEMENT content (article*)>

<!ELEMENT article (url,title,postdate,category,author,summary)>

<!ELEMENT url (#PCDATA)>

<!ELEMENT title (#PCDATA)>

<!ELEMENT postdate (#PCDATA)>

<!ELEMENT category (#PCDATA)>

<!ELEMENT author (#PCDATA)>

<!ELEMENT summary (#PCDATA)>

]>

The code element will almost always return 200. Other code values indicate an error in processing your request. The category field here will display the name of the category.

Here you can find an example of an XML response from OCEAN used for Connect News.

PHP Library

The OCEAN PHP library is a simple, ready-to-go one class library for using the API easily from PHP. This library handles making the request to TalentOyster and parsing the returned XML response for you. This library uses the CURL and domxml libraries in PHP and should work on standard PHP versions of 4 or later.

You can download the library here.

Example

The following example shows how to use the PHP library. In this example we have a simple page with a search form that pulls in and displays jobs from TalentOyster.

<html>

<head>

<title>API Example</title>

</head>

<body>

<form action="apitest.php" method="POST">

<table border="0" cellpadding="4" cellspacing="0">

<tr><td><strong>Keywords</strong></td>

<td><input type="text" name="keywords" size="30" value="<?=$keywords?>"></td></tr>

<tr><td colspan="2"><input type="submit" value="Search Jobs"></td></tr>

</table>

<?php

require "talentoyster.php";

$talent_oyster = new TalentOyster();

$matching_jobs = $talent_oyster -> getJobs($keywords,"Toronto");

for($i=0;$i<count($matching_jobs);$i++){

  echo "<p><a href=\"".$matching_jobs[$i]["url"]."\">".$matching_jobs[$i]["title"]."</a><br><em>";

  echo  $matching_jobs[$i]["company"]." - ".$matching_jobs[$i]["postdate"]."</em><br>";

  echo  "<small>".$matching_jobs[$i]["summary"]."</small></p>\n";

}

?>

</body>

</html>

Below is an example of what the code above actually produces.

TalentOyster OCEAN PHP Library Example output