Get Parametric Values

Retrieves the unique values that occur in a particular field.

The Get Parametric Values API retrieves the unique values that occur in a particular field, which you can use to provide faceted search. For example, if you have a color parametric field, you can use this API to retrieve all the color values that occur in your documents. A common use for this information is to provide filters to end users.

For example:

Quick Start



The API returns a list of the values of the fields that you specify in the field_names parameter that exist in the indexes that you specify in the indexes parameter. The fields that you specify must be parametric or date type fields (see Index Field Types). If you do not specify the indexes parameter, the API uses the wiki_eng public text index.

/1/api/[async|sync]/getparametricvalues/v2?field_names=person_profession&indexes=wiki_eng

You can use any parametric or date type field in a public or private text index. For a list of available fields in the public text indexes, see Public Text Indexes. In your private text indexes, there are a number of standard parametric fields available, depending on the flavor of the text index (see Index Flavors), and you can also add custom parametric fields when you create the text index. For more information about creating and using custom parametric fields, see the Create Text Index API, and the Use Parametric (Faceted) Search documentation.

The API returns a response of the following form:

{
  "fields": [
    {
	  "name": "person_profession",
	  "values": [
	    { "value": "FOOTBALL PLAYER", "count": 107248 },
		{ "value": "PHYSICIAN", "count": 910 },
		{ "value": "ACTOR / ACTRESS", "count": 38068 },
		{ "value": "POLITICIAN", "count": 22663 },
		{ "value": "COLUMNIST", "count": 278 },
		{ "value": "PAINTER", "count": 5893 },
		{ "value": "PRIVATE INVESTIGATOR", "count": 9 },
		{ "value": "WRITER", "count": 3980 },
		{ "value": "FILM DIRECTOR", "count": 7429 },
		{ "value": "BOTANIST", "count": 2585 },
		{ "value": "SINGER", "count": 5662 },
		{ "value": "CHEMIST", "count": 2382 }
	  ]
	}
  ]
}

You can specify multiple fields. For example:

/1/api/[async|sync]/getparametricvalues/v2?field_names=person_profession&field_names=wikipedia_category&indexes=wiki_eng&max_values=10

{
  "fields": [
    {
	  "name": "person_profession",
	  "values": [
	    { "value": "FOOTBALL PLAYER", "count": 107248 },
		{ "value": "PHYSICIAN", "count": 910 },
		{ "value": "ACTOR / ACTRESS", "count": 38068 },
		{ "value": "POLITICIAN", "count": 22663 },
		{ "value": "COLUMNIST", "count": 278 },
		{ "value": "PAINTER", "count": 5893 },
		{ "value": "PRIVATE INVESTIGATOR", "count": 9 },
		{ "value": "WRITER", "count": 3980 },
		{ "value": "FILM DIRECTOR", "count": 7429 },
		{ "value": "BOTANIST", "count": 2585 }
	  ]
	},
    {
	  "name": "wikipedia_category",
	  "values": [
	    { "value": "LIVING PEOPLE", "count": 651505 },
		{ "value": "1991 BIRTHS", "count": 7670 },
		{ "value": "CZECH ICE HOCKEY PLAYERS", "count": 851 },
		{ "value": "LAKE ERIE MONSTERS PLAYERS", "count": 181 },
		{ "value": "HC CESKÉ BUDEJOVICE PLAYERS", "count": 68 },
		{ "value": "DENVER CUTTHROATS PLAYERS", "count": 23 },
		{ "value": "CHILLIWACK BRUINS PLAYERS", "count": 10 },
		{ "value": "EDMONTON OIL KINGS PLAYERS", "count": 14 },
		{ "value": "VICTORIA ROYALS PLAYERS", "count": 1 },
		{ "value": "BOBSLEIGH AT THE 1984 WINTER OLYMPICS", "count": 1 }
	  ]
	}
  ]
}

When you specify multiple field names, by default, the response returns each field separately. This option allows you to create top level filters that specify the total number of documents available for values. You can also create a set of filters that depend on each other, by setting the nest_field_results parameter to true. In this case, the first field that you specify in the field_names array is the top level field, the second field that you specify is the first subfield, and so on. The API finds the values that occur in the first field, and returns values of the second field that occur in fields with this value. For example:

/1/api/[async|sync]/getparametricvalues/v2?field_names=person_profession&field_names=wikipedia_category&indexes=wiki_eng&nest_field_results=true&max_values=3

This API call returns values of the wikipedia_category field that occur in documents with a particular value of the person_profession field.

{
  "fields": [
    {
      "name": "person_profession",
      "values": [
        {
          "value": "FOOTBALL PLAYER",
          "count": 101015,
          "subfield": {
            "name": "wikipedia_category",
            "values": [
              {
                "value": "LIVING PEOPLE",
                "count": 93171
              },
              {
                "value": "ASSOCIATION FOOTBALL GOALKEEPERS",
                "count": 6116
              },
              {
                "value": "SÜPER LIG PLAYERS",
                "count": 1728
              }
            ]
          }
        }
      ]
    }
  ]
}

If any of the subfields are empty or missing from documents with a particular value in the top level field, the subfield is returned with the value null. The response still includes any further subfields, under the null entry.

Limit and Sort Results

By default, Get Parametric Values returns up to 100 possible values for each field, along with the number of documents that the value occurs in. The results are unsorted.

You can use the max_values parameter to restrict the number of field values to return. For example:

/1/api/[async|sync]/getparametricvalues/v2?field_names=person_profession&indexes=wiki_eng&max_values=5

The sort parameter allows you to specify the order that the results return. For example:

/1/api/[async|sync]/getparametricvalues/v2?field_names=person_profession&indexes=wiki_eng&max_values=5&sort=alphabetical

This API call returns the first five professions alphabetically.

{
  "fields": [
    {
	  "name": "person_profession",
	  "values": [
	    { "value": "00 AGENT", "count": 1 },
		{ "value": "ABBESS", "count": 1 },
		{ "value": "ABBOT", "count": 24 },
		{ "value": "ABBÉ", "count": 1 },
		{ "value": "ABOLITIONISM", "count": 1 }
	  ]
	}
  ]
}

Return Field Information

You can set the total_values parameter to true to return the total number of available values for the field. For example:

/1/api/[async|sync]/getparametricvalues/v2?field_names=person_profession&indexes=wiki_eng&max_values=5&total_values=true

{
  "fields": [
    {
	  "name": "person_profession",
	  "total_values": 1422,
	  "values": [
	    { "value": "FOOTBALL PLAYER", "count": 107248 },
		{ "value": "PHYSICIAN", "count": 910 },
		{ "value": "ACTOR / ACTRESS", "count": 38068 },
		{ "value": "POLITICIAN", "count": 22663 },
		{ "value": "COLUMNIST", "count": 278 }
	  ]
	}
  ]
}

If you do not want to return the information about the number of documents that each field occurs in, you can set the document_count parameter to false. For example:

/1/api/[async|sync]/getparametricvalues/v2?field_names=person_profession&indexes=wiki_eng&max_values=50&document_count=false

You can use the values that you retrieve with the Get Parametric Values API in a subsequent Query Text Index API call. For example, the following query returns the 24 documents that have the value ABBOT in the person_profession field, and prints that field in the results.

/1/api/[async|sync]/querytextindex/v1?text="*"&indexes=wiki_eng&field_text=MATCH{abbot}:person_profession&print_fields=person_profession

Get Date Values

When you request parametric values for a date type field that contains time information as well as dates, Haven OnDemand returns the values in blocks of one hour by default. For example:

/1/api/sync/getparametricvalues/v2?field_names=created_date&indexes=news_eng&max_values=10&sort=number_decreasing

This API call returns a response of the following type:

{
  "fields": [
    {
      "name": "created_date",
      "values": [
        { "value": "2016-07-19 14:00:00", "count": 1 },
        { "value": "2016-07-19 13:00:00", "count": 274 },
        { "value": "2016-07-19 12:00:00", "count": 189 },
        { "value": "2016-07-19 11:00:00", "count": 140 },
        { "value": "2016-07-19 10:00:00", "count": 127 },
        { "value": "2016-07-19 09:00:00", "count": 65 },
        { "value": "2016-07-19 08:00:00", "count": 49 },
        { "value": "2016-07-19 07:00:00", "count": 64 },
        { "value": "2016-07-19 06:00:00", "count": 135 },
        { "value": "2016-07-19 05:00:00", "count": 122 }
      ]
    }
  ]
}

The date values return in ISO-8601 format. It can also return the values after upper end of range and before lower end of range. The sort value in the example call above ensures that the most recent dates return first.

You can use the date_period parameter to specify the most appropriate date grouping for your data. An hour is the smallest grouping, but you can also specify day, week, month, year, and century. For example:

/1/api/sync/getparametricvalues/v2?field_names=created_date&indexes=news_eng&max_values=10&sort=number_decreasing&date_period=day

You can adjust the date_period to provide the best grouping for your data. For example, if the data consists of tweets, an hour might be a suitable grouping. However, if your data contains historical information, the year or century options might be more suitable.

Use Get Parametric Values with a Query

By default, Get Parametric Values returns all the values available for a particular field in the text index (up to max_values). You can also add the text and field_text parameters to apply the Get Parametric Values request to the results of a particular query. These parameters accept the same values and syntax as the text and field_text parameters in the Query Text Index API.

For example, if you have a query filter that uses the parametric person_profession field, you can either run Get Parametric Values to return all possible professions in the wiki_eng text index, or you can add a query to return only person_profession values that occur in documents about painters:

/1/api/[async|sync]/getparametricvalues/v2?field_names=person_profession&indexes=wiki_eng&max_values=10&text=painters

The API finds documents that match the query, and returns a list of values for the person_profession field that occur in these documents:

{
  "fields": [
    {
	  "name": "person_profession",
	  "values": [
	    { "value": "PAINTER", "count": 8758 },
		{ "value": "ACTOR / ACTRESS", "count": 3762 },
		{ "value": "ARCHITECT", "count": 423 },
		{ "value": "ARTIST", "count": 196 },
		{ "value": "PHOTOGRAPHER", "count": 94 },
		{ "value": "COMPOSER", "count": 410 },
		{ "value": "PIANIST", "count": 135 },
		{ "value": "FOOTBALL PLAYER", "count": 649 },
		{ "value": "SCULPTOR", "count": 359 },
		{ "value": "DRAUGHTSMAN", "count": 4 }
	  ]
	}
  ]
}

You can also use field_text to add an additional field restriction. For example, the following query finds the values of the person_profession field that occur in documents that match the text painters, and which have the wikipedia_category value modern painters.

/1/api/[async|sync]/getparametricvalues/v2?field_names=person_profession&indexes=wiki_eng&field_text=MATCH{modern painters}:wikipedia_category&text=painters

The Get Parametric Values API also allows you to set the min_score parameter for the query, to return only values for the specified field that match your query with a specified relevance score. This option means that you can restrict the list of values to ones that occur only in the most relevant documents that match your query.

If you set total_values to true when you also set text or field_text, the number of values that returns is the number of values in the set of documents that match your query, rather than the total number of values in the text index.

Synchronous
https://api.havenondemand.com/1/api/sync/getparametricvalues/v2
Asynchronous
https://api.havenondemand.com/1/api/async/getparametricvalues/v2
Authentication

This API requires an authentication token to be supplied in the following parameter:

Parameter Description
apikey The API key to use to authenticate the API request.
Parameters

This API accepts the following parameters:

Required
Name Type Description
field_names
array<string> The field names to return values for.
Optional
Name Type Description
date_period
enum The time interval to use for grouping together date values. This option only has an effect if one or more fields that you specify in field_names contain date values. Default value: hour.
document_count
boolean Set to true to show the number of documents that contain a parametric tag value. Default value: true.
nest_field_results
boolean Set to true to find sets of values that occur together in documents. The results are returned in a hierarchical structure, with the first field in the field_names array at the top, followed by the second, and so on. Default value: false.
field_text
string The fields that result documents must contain, and the conditions that these fields must meet for the documents to return as results. See Field Text Operators.
indexes
array<resource> The text index to use to perform the parametric search. Default value: [wiki_eng].
max_values
number The maximum number of values to return for each matched field name. This parameter may be capped by your index flavour. Default value: 100.
min_score
number The minimum percentage relevance that results must have to the query to return. Default value: 0.
sort
enum The criteria to use for the result display order. By default, results are not sorted. Default value: off.
text
string The query text. See Boolean and Proximity Operators. Default value: *.
total_values
boolean Set to true to show the total number of values for each field (disregarding any max_values limit on the request). Default value: false.
Enumeration Types

This API's parameters use the enumerations described below:

date_period
The time interval to use for grouping together date values. This option only has an effect if one or more fields that you specify in field_names contain date values.
century Century
Group date values together by the century in which they occurred.
year Year
Group date values together by the year in which they occurred.
month Calendar month
Group date values together by the month in which they occurred.
week Week
Group date values together in periods of one week.
day Day
Group date values together in periods of one day.
hour Hour
Group date values together in periods of one hour.
sort
The criteria to use for the result display order. By default, results are not sorted.
document_count Number of matching documents (descending)
Order by the number of documents that contain the field, highest document count first. You can use this sort only when the document_count parameter is set to true.
reverse_document_count Number of matching documents (ascending)
Order by the number of documents that contain the field, lowest document count first. You can use this sort only when the document_count parameter is set to true.
alphabetical Alphabetical
Order alphabetically.
reverse_alphabetical Reverse alphabetical
Order in reverse alphabetical order.
number_increasing Numeric field value (lowest number first)
Order by the numeric value of the field, with the lowest number first. This option reverts to alphabetical order for non-numeric values.
number_decreasing Numeric field value (highest number first)
Order by the numeric value of the field, with the highest number first. This option reverts to alphabetical order for non-numeric values.
date Date value (most recent date first)
Order values by date, with the most recent date listed first. For this option, the fields that you specify in field_names must contain date values.
reverse_date Date value (earliest date first)
Order values by date, with the earliest date is listed first. For this option, the fields that you specify in field_names must contain date values.
off No sorting

This API returns a JSON response that is described by the model below. This single model is presented both as an easy to read abstract definition and as the formal JSON schema.

Asynchronous Use

Additional requests are required to get the result if this API is invoked asynchronously.

You can use /1/job/status/<job-id> to get the status of the job, including results if the job is finished.

You can also use /1/job/result/<job-id>, which waits until the job has finished and then returns the result.

Model
This is an abstract definition of the response that describes each of the properties that might be returned.
Get Parametric Values Response {
fields ( array[Field] ) Matched parametric fields.
warnings ( array[Warnings] , optional)
}
Field {
name ( string ) The name of this particular field.
total_values ( integer , optional) The total number of values (disregarding any max_values limit on the request).
values ( array[Field-Value] ) A list of the values of this field in the query results.
}
Field-Value {
value ( string ) A particular value of this field.
count ( integer , optional) The number of times this value exists in this field, shown when document_count is true.
subfield ( object , optional) Dependent field values, shown when nest_field_results is true.
}
Get Parametric Values Response:Warnings {
code ( integer , optional)
details ( object , optional)
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "definitions": {
        "field-value": {
            "type": "object",
            "properties": {
                "value": {
                    "type": "string"
                },
                "count": {
                    "type": "integer",
                    "minimum": 0
                },
                "subfield": {
                    "type": "object",
                    "items": {
                        "$ref": "#/definitions/subfield"
                    }
                }
            },
            "required": [
                "value"
            ]
        },
        "field": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string"
                },
                "total_values": {
                    "type": "integer",
                    "minimum": 0
                },
                "values": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/field-value"
                    },
                    "minItems": 0,
                    "uniqueItems": true
                }
            },
            "required": [
                "name",
                "values"
            ]
        },
        "subfield-value": {
            "type": "object",
            "properties": {
                "value": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "count": {
                    "type": "integer",
                    "minimum": 0
                },
                "subfield": {
                    "type": "object",
                    "items": {
                        "$ref": "#/definitions/subfield"
                    }
                }
            },
            "required": [
                "value"
            ]
        },
        "subfield": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string"
                },
                "values": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/subfield-value"
                    },
                    "minItems": 0,
                    "uniqueItems": true
                }
            },
            "required": [
                "name",
                "values"
            ]
        }
    },
    "type": "object",
    "additionalProperties": false,
    "properties": {
        "fields": {
            "type": "array",
            "items": {
                "$ref": "#/definitions/field"
            }
        },
        "warnings": {
            "type": "array",
            "items": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                    "code": {
                        "type": "integer"
                    },
                    "details": {
                        "type": "object"
                    }
                }
            }
        }
    },
    "required": [
        "fields"
    ]
}
https://api.havenondemand.com/1/api/sync/getparametricvalues/v2
/api/api-example/1/api/sync/getparametricvalues/v2
Examples
See this API for yourself - select one of our examples below.
Get Parametric Values
Get all values for the professions parametric field on Wikipedia
Match Parametric Values
Count the number of documents that match several parametric values on Wikipedia
Match Parametric Values
Find the top ten producers of inkjet patents
Match Parametric Values
Find the top categories of Wikipedia pages talking about R2-D2
Parameters
Required
Name Type Value
field_names
array
Add another value
Optional
Name Type Value
date_period
enum
document_count
boolean
(Default: True)
nest_field_results
boolean
(Default: False)
field_text
string
indexes
array
max_values
number
min_score
number
sort
enum
text
string
total_values
boolean
(Default: False)


ASync – Response An error occurred making the API request
Response Code:
Response Body

	
Making API Request…
Checking result of job

To try this API with your own data and use it in your own applications, you need an API Key. You can create an API Key from your account page - API Keys.

Output Refresh An error occurred making the API request View Input
Rendered RawHtml Response
Result Display
Response Code:
Response Body:

			
Make this call with curl

Version 2 (2016-07-25)

This page outlines the changes to the Get Parametric Values API from the previous version.

  • The response format has been improved. The response object contains a section for each of the fields that you request, and value and count properties for each value.
  • Date values are now returned in ISO-8601 date format in the response for a date type field.
  • The field_name parameter has been renamed to field_names. You can set multiple field_names parameters in an array to return parametric values for multiple fields.
  • The date_period parameter has been added. This parameter allows you to specify the date groupings to use when you set field_names to a date type field.
  • The sort parameter now accepts new sort options date, reverse_date, and reverse_document_count.
  • The total_values parameter has been added. This parameter allows you to return the total number of available values for the specified parametric fields.


If you would like to provide us with more information then please use the box below:

We will use your submission to help improve our product.