Parameter Types
Types of Parameters in Haven OnDemand APIs.

API Parameter Types

The Haven OnDemand API pages display a Type for each parameter. This page describes the different types, and acceptable input values.

String

String parameters accept text values. The exact value you must use depends on the API. For example, for the Query Text Index API, the text parameter accepts almost any query text value, while the max_date parameter accepts a date in one of the formats listed on the Parameter Date Formats documentation page.

You can percent-encode spaces in your text (as %20), or use a plus sign (+). If your string includes special characters, such as commas (,), plus signs (+), and ampersands (&), you must percent-encode these characters in the string.

text=some%20query%20text
max_date=20%2F03%2F2015

Boolean

Boolean parameters accept the values true and false. For example:

total_results=true
document_count=false

Number

Number parameters accept numeric values, including integers and decimal values (with a period (.) as the decimal point). For example:

start=10
min_score=75.5

Enum

Enum parameters accept one of a fixed set of values. The API documentation Request page displays an Enumeration Types section, listing the accepted values for these parameters in each API that has this type of parameter. The API Try page also allows you to select one of the enum values for these parameters.

highlight=terms

Array

Array parameters accept multiple values. Each individual value might have one of the previous types (such as a string or an enum), but you can specify multiple options.

For example, the indexes parameter in Search APIs can take the name of any text index, while the field_types parameter for the Retrieve Index Fields API accepts one or more of a set of enum values.

You can specify the array parameters by adding the parameter name multiple times in your API input string. For example:

indexes=wiki_eng&indexes=mycustomindex
field_types=parametric&field_types=date&field_types=reference

Haven OnDemand preserves the order in which the values of an array are passed.

For example, the following:

indexes=t1&indexes=t2&indexes=t3

would result in an array like this:

indexes[0] = t1
indexes[1] = t2
indexes[2] = t3

Binary

Binary parameters accept a file upload. The appropriate file format depends on the API that you are using, for example, image files for the OCR API, video or audio tracks for speech to text, or written formats for text indexing and entity extraction. See Supported Media Formats and Supported Document and Container File Formats for lists of file types supported by Haven OnDemand

You must use an HTTP POST request to submit files in binary parameters. For example:

curl -X POST --form "file=@RecSpeechTest.wma" --form "language=en-US-tel" --form "apikey=mykey" https://api.havenondemand.com/1/api/async/recognizespeech/v1 

JSON

JSON parameters are used in many APIs to submit structured data, such as the items in a table, database or list, in readable formats to Haven OnDemand.

Two of the most characteristic uses of JSON parameters are:

  • to submit configurations for connectors. See Connectors.
  • with the Job API, which allows you to submit multiple asynchronous API requests with a single HTTP request. For more on submitting jobs see Synchronous and Asynchronous API.
The formats depend on the APIs. Examples include: