havenondemand / havenondemand
This library allows you to quickly and easily make requests to Haven OnDemand's APIs.
Requires
- php: >=5.3
This package is not auto-updated.
Last update: 2024-03-16 16:09:04 UTC
README
Official PHP client library to help with calling Haven OnDemand APIs.
What is Haven OnDemand?
Haven OnDemand is a set of over 70 APIs for handling all sorts of unstructured data. Here are just some of our APIs' capabilities:
- Speech to text
- OCR
- Text extraction
- Indexing documents
- Smart search
- Language identification
- Concept extraction
- Sentiment analysis
- Web crawlers
- Machine learning
For a full list of all the APIs and to try them out, check out https://www.havenondemand.com/developer/apis
Integrate HODClient into php project
Download from Packagist and include in app
Run the following command from your terminal (composer must be installed)
composer require havenondemand/havenondemand
Place the following line in your app to include the library
include './vendor/havenondemand/havenondemand/lib/hodclient.php';
include './vendor/havenondemand/havenondemand/lib/hodresponseparser.php';
Download directly from Github
- Download the HODClient and HODResponseParser libraries for PHP.
- Unzip the file and copy the hodclient.php and hodresponseparser.php under the lib folder to your project folder.
Using the library
Creates and initializes a HODClient object.
HODClient($apiKey, $version = "v1")
$apiKey
is your developer apikey.$version
Haven OnDemand API version. The default value is "v1".
Example code:
include "hodclient.php"
$hodClient = new HODClient("API_KEY");
If you want to change the API version without the need to recreate the instance of the HOD client.
SetVersion($newversion)
$newVersion
a string to specify an API version as "v1" or "v2"
If you want to change the API_KEY without the need to recreate the instance of the HOD client.
SetAPIKey($newApiKey)
newApiKey
a string to specify a new API_KEY
Function GetRequest
Sends a HTTP GET request to call an Haven OnDemand API.
GetRequest($paramArr, $hodApp, $async, $callback)
$paramArr
is an array() containing key/value pair parameters to be sent to a Haven OnDemand API, where the keys are the parameters of that Haven OnDemand API.
Note: If a parameter type is an array<>, the value must be defined as an array() or [].
E.g.:
$sources = array(); array_push($sources, "http://www.cnn.com"); array_push($sources, "http://www.bbc.com"); $paramArr = array( 'url' => $sources, 'entity_type' => ["people_eng","places_eng","companies_eng"] );
$hodApp
is a string to identify a Haven OnDemand API. E.g. "extractentities".$async [true | false]
specifies API call as Asynchronous or Synchronous.$callback
the name of a callback function. If the $callback is omitted, or is an empty string "", this function will return a response.
Example code:
// Call the Entity Extraction API synchronously to find people, places and companies from CNN website.
$paramArr = array(
'url' => "http://www.cnn.com",
'entity_type' => ["people_eng","places_eng","companies_eng"]
);
$response = GetRequest($paramArr, HODApps::ENTITY_EXTRACTION, false);
Function PostRequest
Sends a HTTP POST request to call a Haven OnDemand API.
PostRequest($paramArr, $hodApp, $async, $callback)
$paramArr
is an array() containing key/value pair parameters to be sent to a Haven OnDemand API, where the keys are the parameters of that Haven OnDemand API.
Note: If a parameter type is an array<>, the value must be defined as an array() or [].
E.g.:
$sources = array();
array_push($sources, "http://www.cnn.com");
array_push($sources, "http://www.bbc.com");
$paramArr = array(
'url' => $sources,
'entity_type' => ["people_eng","places_eng","companies_eng"]
);
$hodApp
is a string to identify an Haven OnDemand API. E.g. "ocrdocument".$async [true | false]
specifies API call as Asynchronous or Synchronous.$callback
the name of a callback function. If the $callback is omitted, or is an empty string "", this function will return a response.
Example code:
// Call the OCR Document API asynchronously to scan text from an image file.
$paramArr = array(
'file' => "full/path/filename.jpg",
'mode' => "document_photo")
);
$response = $hodClient->PostRequest($paramArr, HODApps::OCR_DOCUMENT, true);
Function GetJobResult
Sends a request to Haven OnDemand to retrieve content identified by a job ID.
GetJobResult($jobID, $callback)
$jobID
the job ID returned from an Haven OnDemand API upon an asynchronous call.$callback
the name of a callback function, which the HODClient will call back and pass the response from server. If the $callback is omitted, or is an empty string "", this function will return a response.
Function GetJobStatus
Sends a request to Haven OnDemand to retrieve the status of a job identified by a job ID.
GetJobStatus($jobID, $callback)
$jobID
the job ID returned from an Haven OnDemand API upon an asynchronous call.$callback
the name of a callback function, which the HODClient will call back and pass the response from server. If the $callback is omitted, or is an empty string "", this function will return a response.
Function GetRequestCombination
Sends a HTTP GET request to call a combination API.
GetRequestCombination($paramArr, $hodApp, $async, $callback)
$paramArr
is an array() containing key/value pair parameters to be sent to a Haven OnDemand API, where the keys are the parameters of the calling API.
Note: If a parameter type is an array [] or a JSON object {}, the value must be quoted as a string. E.g.:
$paramArr = array(
'url' => 'http://www.bbc.com',
'entity_type' => '["people_eng","places_eng","companies_eng"]'
);
$hodApp
is the name of the combination API you are calling$async [true | false]
specifies API call as Asynchronous or Synchronous.$callback
the name of a callback function. If the $callback is omitted, or is an empty string "", this function will return a response.
Example code:
// Call the Entity Extraction API synchronously to find people, places and companies from CNN website.
$paramArr = array(
'url' => "http://www.cnn.com",
'entity_type' => '["people_eng","places_eng","companies_eng"]'
);
$response = GetRequestCombination($paramArr, "combination_api_name", false);
Function PostRequestCombination
Sends a HTTP POST request to call a combination API.
PostRequestCombination($paramArr, $hodApp, $async, $callback)
$paramArr
is an array() containing key/value pair parameters to be sent to a Haven OnDemand API, where the keys are the parameters of the calling API.
Note: If a parameter type is an array [] or a JSON object {}, the value must be quoted as a string. E.g.:
$paramArr = array(
'url' => 'http://www.bbc.com',
'entity_type' => '["people_eng","places_eng","companies_eng"]'
);
$hodApp
is the name of the combination API you are calling$async [true | false]
specifies API call as Asynchronous or Synchronous.$callback
the name of a callback function. If the $callback is omitted, or is an empty string "", this function will return a response.
Example code:
// Call the Entity Extraction API synchronously to find people, places and companies from CNN website.
$paramArr = array(
'url' => "http://www.cnn.com",
'entity_type' => '["people_eng","places_eng","companies_eng"]'
);
$response = PostRequestCombination($paramArr, "combination_api_name", false);
Demo code 1:
Call the Entity Extraction API to extract people and places from cnn.com website with a synchronous GET request
<?php include "hodclient.php"; // implement callback function function requestCompletedWithContent($response) { $jsonStr = stripslashes($response); $respObj = json_decode($jsonStr); $people = ""; $places = ""; $entities = $respObj->entities; for ($i = 0; $i < count($entities); $i++) { $entity = $entities[$i]; if ($entity->type == "people_eng") { $people .= $entity->normalized_text . "; // parse any other interested information about this person ... } else if ($entity->type == "places_eng") { $places .= $entity->normalized_text . "; // parse any other interested information about this place ... } } echo "PEOPLE: " . $people; echo "</br> echo "PLACES: " . $places; } $hodClient = new HODClient("YOUR-API-KEY"); $paramArr = array( 'url' => "http://www.cnn.com", 'entity_type' => ["people_eng","places_eng"] ); try { $hodClient->GetRequest($paramArr, HODApps::ENTITY_EXTRACTION, false, 'requestCompletedWithContent'); } catch (Exception $ex) { echo $ex->getMessage(); } ?>
Demo code 2:
Call the OCR Document API to scan text from an image with an asynchronous POST request
<?php include "hodclient.php"; include "hodresponseparser.php"; // implement callback function function requestCompletedWithJobId($response) { global $hodClient; $resp = new HODJobIDParser($response); if ($resp->error != null) { echo (json_encode($resp->error)); }else { $hodClient->GetJobStatus($resp->jobID, 'requestCompletedWithContent'); } } // implement callback function function requestCompletedWithContent($response) { $resp = new HODResponseParser($response); if ($resp->error != null){ $err = $resp->error; if ($err->error == HODErrorCode::QUEUED) { sleep(2); $hodClient->GetJobStatus($err->jobID, 'requestCompletedWithContent'); } else if ($err->error == HODErrorCode::IN_PROGRESS) { sleep(5); $hodClient->GetJobStatus($err->jobID, 'requestCompletedWithContent'); } else { $result = "<b>Error:</b></br>"; $result .= $resp->error->error . "</br>"; $result .= $resp->error->reason . "</br>"; } } else { $result = ""; $textBlocks = $response->text_block; for ($i = 0; $i < count($textBlocks); $i++) { $block = $textBlocks[$i]; $result .= "<html><body><p>"; $result .= preg_replace("/\n+/", "</br>", $block->text); $result .= "</p></body></html>"; } } echo "RECOGNIZED TEXT: ".$result; } $hodClient = new HODClient("YOUR-API-KEY"); $paramArr = array( 'url' => "https://www.hodondemand.com/sample-content/images/speccoll.jpg", 'mode' => "document_photo" ); try { $hodClient->PostRequest($paramArr, HODApps::OCR_DOCUMENT, true, 'requestCompletedWithJobId'); } catch (Exception $ex) { echo $ex->getMessage(); } ?>
License
Licensed under the MIT License.