Using the Haven OnDemand APIs

What is an API?

Let us start by answering this basic question. Haven OnDemand Application Programming Interfaces are frameworks that let you interact with remote applications and data in the cloud.

APIs are like messengers that take requests (calls) to a remote system, to perform an action, and bring back a response. You make these calls using HTTP GET and POST requests. The APIs return their responses as JSON strings.

You can integrate the calls and responses into your own software applications and combine them to create originals. Applications that make use of multiple APIs in sequence or together are called mashups.

In addition to APIs and some public datasets for practice, Haven OnDemand provides software libraries in a several popular languages to get you up and running with pre-coded functions, documentation and examples.

Common Features of Haven OnDemand APIs

The common purpose of Haven OnDemand APIs is data analytics. They allow you to examine information which you submit to them. You provide this information, which can be located on a local repository or at another web location, as an input parameter. The APIs process the input data, in some cases by comparing it to other cloud-based information, and return a response.

Let us look at the parts of a typical Haven OnDemand API URL:


  • https://: The protocol.
  • The domain.
  • /1: The platform version.
  • /sync: The mode, can be sync for synchronous, async for asynchronous. See Synchronous and Asynchonous Requests.
  • /querytextindex: The name of the API being called, in this case, Query Text Index. This API is a search engine that attempts to match an input query with a specified body of information or dataset. See Search, Text Analysis and Indexing APIs.
  • /v1: The version of the API being called.
  • ? and & Separators. The ? marks the start of the query, and the &s separate the different fields in the query.
  • text=%22taylor+swift%22: Input, in this case, a string of text to search for, Taylor Swift. For more on the kinds of input you can submit, see API Parameter Types: Input, Required and Action.
  • indexes=news_eng: The dataset in which the Query Text Index API attempts to find the input text. In this case, it is a public dataset of news feeds in English. The indexes parameter is mandatory for the Query Text Index API. For more on indexes see Search, Text Analysis and Indexing apis.
  • print_fields=title&promotion=false&sort=date: Action parameters, to set up how the response should be formatted. In this case, it prints the title of the articles and sorts them by date, with no promotions on any string.
  • apikey=my_apikey: Your private key, giving you secure access to Haven OnDemand and the datasets. For more information, see The Apikey.

GET and POST Requests

Requests to the Haven OnDemand APIs are made with the HTTP GET and POST methods. Depending on the API, one or the other method may be more appropriate.

Generally speaking, you should use a POST request in all cases where you upload a file to the API for processing, for example, a sound file to the Speech Recognition API or an image or document file to the OCR Document API. POST requests are also used with asynchronous Job requests.

For more information, see HTTP GET and POST Methods.

Synchronous and Asynchronous Requests

Most APIs can be run in synchronous or asychronous mode; some can only run asynchronously.

A synchronous request returns its response immediately. Use it for quick results and smaller jobs.

An asynchronous request is for actions that might take a long time, such as converting audio to text. Use this mode to handle larger files, or to submit multiple actions in one job.

For more information, see Synchronous and Asynchronous API Requests.

API Parameter Types: Input, Required and Action

Each API page has a Request tab, which details the parameters to submit for the API to work. There are three kinds:

  • Input: APIs that require you to submit information for analysis commonly give you a choice of three input mechanisms:
    • Upload a file. Note that you can only use a POST method for this.
    • Submit the reference of an object already stored in the Haven OnDemand cloud.
    • Submit a url.

    You must choose only one of these per call.

Other APIs require different inputs, for example, APIs performing actions on Connectors require the name of the connector.

  • Required: These are parameters the APIs need to be able to run. For example, the APIkey is required for all Haven OnDemand requests. Search APIs require the public or private dataset in which to search.
  • Action: These parameters configure the behavior of the API and format the response. For example, for search APIs, they set the maximum number of returns or the sorting order. For OCR or Speech Recognition, they set the language or audio quality.

The APIkey

Your private developer key, called your apikey, establishes your credentials as a Haven OnDemand user, secures your access, and guards the privacy of any data you upload or store in the Haven OnDemand cloud.

To get your apikey, sign up as described on our Getting Started page.

You must use your apikey in every call you make to Haven OnDemand.

API Categories

Beyond their common function of data analytics, the Haven OnDemand APIs fall into a range of categories, for audio and video, images, maps, text, searching and trans-formatting, each of which requires different types of handling.

See the API list for a categorized list of APIs.

Search, Text Analysis and Indexing APIs

Although Haven OnDemand APIs are not limited to search and text based analytics, this is a particularly strong and important grouping, with its own set of usage considerations.

You can use the powerful search algorithms against private datasets which you submit, or against public datasets which Haven OnDemand provides for you.

Public Datasets and their Fields

Haven OnDemand gives you access to a range of public datasets, which you can use as samples to model your applications or test your queries.

You can view a list of the public datasets.

Important information you can find on that page includes:

  • The lists of fields in each index, which you can call in faceted searches. To view the list of fields, expand the More Detail button under each dataset.
  • The type for each field. Certain search functionalities can only be used with certain types of data (for example, numeric queries can only be run on fields of Numeric type). For the multilingual News feeds, click the + sign to the left of the title to see what news sources are being included in the index.

Unstructured Text Indexing

The power of Haven OnDemand search algorithms is that they can run on unstructured data. Anything containing text in any of the formats currently used around you – pdfs, spreadsheets, Word files, images, audio and video - can be converted into a format that the APIs can use.

The uploading of documents to the Haven OnDemand cloud for conversion, analysis and storage is called Unstructured Text Indexing. The APIs in this category let you create and manage these private online indexes.

The Default Index and its fields

If you set up a private index of documents in which to run the searches, it will have a set range of fields by default.

Different flavors of index have different configurations of standard fields, and some flavors allow you to configure custom fields with particular field types.

You can view a list of the fields supported by the Explorer text index that is available in the Freemium developer offers, here.

Machine Learning APIs

Another exciting category of Haven OnDemand APIs are those devoted to, or making use of, machine learning. These APIs are already trained to draw upon information that has been supplied to them. For example:

  • The Image Recognition API is trained to compare an image you submit to a database of nearly a thousand corporate logos.
  • The Entity Extraction API can identify people, places or companies, phone numbers, dates, Web addresses, and credit card numbers, in submitted text.
  • The Find Similar API looks for similarities between your input and data you yourself have already uploaded to a private index.

How to use the APIs

The API Pages

From the API list, you can access information about using any one of the APIs.

Click on an API to view its individual documentation page. Each documentation page has four tabs:

  • Overview: which gives you the basic functions and parameters of the API, and examples of code.
  • Request: a detailed list of the Input, Required and Action parameters that can be used with the API.
  • Response: the information the API can return when it is run, and examples of the JSON schema in which the results are formatted.
  • Try It: a UI to try out the API on sample data. The data can be supplied in the UI, or you can use your own in some cases.

Tip: if you do not see your API key and the full set of exposed options on the Try It tab of an API, make sure you are logged in.

Running an API from the Try It page

The API Try It pages are non-technical demonstrations of the APIs, allowing you to try them without having to code anything. You can enter the request parameters from a GUI, which also displays the resultant json strings.

cURL Calls

The Try It pages also automatically generate GET and POST cURL calls for the query from the request parameters submitted. Scroll down to find these at the bottom of the page after the Try It has been run.

curl "*&absolute_max_results=100&field_text=LESS%7B100%7D%3Awfb_area&ignore_operators=false&indexes=world_factbook&print_fields=wfb_flag&promotion=false&total_results=false&apikey=your_apikey"
curl -X POST --form "text=*" --form "absolute_max_results=100" --form "field_text=LESS{100}:wfb_area" --form "ignore_operators=false" --form "indexes=world_factbook" --form "print_fields=wfb_flag" --form "promotion=false" --form "total_results=false" --form "apikey=your_apikey"

You can copy and paste these calls into a command window to run them directly, or refer to them to help you set up equivalent queries in your code.

Proxy Settings

If you are accessing the APIs through a proxy, you might need to provide the proxy address in your code samples, or set it in your computer’s environment variables.

Running API Jobs

You can batch-run several API calls together using the Job API. This takes as input a JSON object, in which each of the actions you want to perform are specified in an array. For more on using the Job API, see Synchronous and Asynchronous API Requests.

Calling the API from code

As a developer, you most commonly call the APIs from your code.

Haven OnDemand has created a range of code libraries in the most common programming languages, containing the more routine functions such as HTTP methods or handling jobs and asynchronous calls, so you can be up and running quickly with more creative things.

  • Android v1
  • Node.js
  • Java (in progress)
  • Angular.js (in progress)
  • Go
  • Python
  • IOS –Swift
  • PHP
  • Windows 8.1
  • R
  • Salesforce
  • Ruby
  • Force.Com
  • Julia

For a list of these, as well as download facilities, sample code and resources, see our API Client Libraries page.

Examples with Python

By way of example, here are some simple applications using the Python wrapper.


The instructions assume you have a version 2 or 3 of Python installed on your machine. The sample code should work with both.

The installation utility pip must also be installed. You can get pip from

Installing the havenondemand packages

On the page, click Clone or Download zip to clone or download and unzip, the havenondemand packages for Python.

See the Readme section of the page for basic instructions on installing and using the SDK.

If you are installing through a proxy, use the command:

pip install --proxy http://proxy_URL:proxy_port havenondemand

To install the latest version from Github, use this command:

pip install --proxy http://proxy_URL:proxy_port git+

See the examples at

To run the code samples, copy-paste them into your Python editor (removing the line numbers) and enter your apikey in the placeholder at line 3.

This is a simple demonstration of the Entity Extraction API. It uses a GET method with error handling, to extract people, places and companies from the homepage URL of the CNN news site.

Mashup of OCR with the Sentiment Analysis.

This application submits a photograph of a text snippet, review,jpg, with a POST method to HODApps.OCR_DOCUMENT, which converts it to text. Then it submits the result to HODApps.ANALYZE_SENTIMENT. The final result is formatted into a readable form before printing to standard output.

Download the input file from to a local directory and modify the path in line 7 accordingly.

Similar to Demo1, this example demonstrates an asynchronous call, using the Job API and a Job Status request.

For more information on these, see Synchronous and Asynchronous API.

Mashup of Speech or Character recognition with Sentiment Analysis.

This example demonstrates asynchronous handling of either an audio file, attendant.mp3, or a photo of a text snippet, review.jpg. After posting to HODApps.RECOGNIZE_SPEECH or HODApps.OCR_DOCUMENT depending on the input, it extracts the result of the job and sends it to HODApps.ANALYZE_SENTIMENT before formatting and printing the output.

Download the input files from

and to a local directory.

Modify the paths in lines 81 and 83 accordingly.

Switch the definition of hodApp at line 78 between HODApps.RECOGNIZE_SPEECH and HODApps.OCR_DOCUMENT to test both options.