Get Parametric Ranges

Retrieves numeric values that occur in a particular field.

The Get Parametric Ranges API retrieves the values that occur in a particular numeric field, organized into a set of value ranges. You can use this to provide faceted search for continuous numeric values.

For example, if you have a price numeric field, you can use this API to retrieve all the price values that occur in your documents, arranged in groupings (0-10, 10-20, and so on). You can specify the ranges to use for your values, so that the groupings are sensible for the range of values that occur in the field. A common use for this information is to provide filters to end users.

Quick Start

The API returns the values of the field that you specify in the field_names parameter that exist in the indexes that you specify in the indexes parameter. The response values are returned in ranges that you specify by using the ranges parameter. The fields that you specify must be Numeric type (see Index Field Types). If you do not specify the indexes parameter, the API uses the wiki_eng public text index.

The ranges parameter accepts the following syntax for each field:

FIXED{RangeBoundaries}:FieldName

where:

RangeBoundaries is a comma-separated list of the boundaries of the ranges that you want to use. You must specify at least two values, in increasing numeric order. You can use a period (.) as the first or last element in the list, to specify open-ended ranges. You can also use scientific notation to specify values, by using an E (for example 1E6 is 1,000,000).

FieldName is the name of the field that you want to return the range values for. You must also list this field in the field_names parameter. The field can be any Numeric type field. You can use Wildcards in the FieldName, to use the same ranges for multiple fields (as long as the fields are specified in the field_names parameter).

The ranges are inclusive at the lower bound, and exclusive at the upper bound. For example, for the range examples above, the value 50,000,000 is included in the 50-100 million range only.

You can specify multiple fields by setting an array of field_names parameters. In this case, you can also specify multiple range sets in the ranges parameter. In ranges, separate the multiple ranges with a plus sign (+). For example:

The API uses a single open-ended range for any field that does not have an explicit definition in ranges.

Determine the Ranges to Use

The value_details parameter allows you to return some extra information about the values that occur in the field. You can set this parameter to true to return the minimum and maximum value in the field, the mean value, the sum of all values, and the total number of values in this field.

You can use this additional information to tune the ranges that you create. For example:

By default, the API returns up to 100 ranges for each field, along with the number of documents that have a value in the range.

You can use the max_ranges parameter to restrict the number of ranges to return. For example, you can use this option with the document_count sort option to return only the top few ranges of values. For example:

You can also set the total_ranges parameter to true to return the total number of available ranges for the field in the response. This number will match the total number of ranges you request (ignoring any restrictions that you add with max_ranges).

Use the Get Parametric Ranges Results

Get Parametric Ranges returns only the ranges of values that occur in your documents. You can use these values to present filters to your users in a user interface.

You can use the values to retrieve the associated documents by generating a subsequent Query Text Index API call. For example, the following query returns the references of documents that have a population value between 1 and 50 million in the place_population field, and prints that field in the results.

Use Get Parametric Ranges with a Query

You can add a query to your Get Parametric Ranges request in the same way as for the Get Parametric Values API, by adding the text and field_text parameters. These parameters restrict the Get Parametric Ranges results to documents that match your 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 numeric place_population field, you might add a query to Get Parametric Ranges to return only place_population values that occur in documents that mention capital cities:

You can also use field_text to add an additional field restriction. For example, the following API call finds values of the place_population field for documents in the wiki_eng text index that have the value Cities in Switzerland in the wikipedia_category field.

/1/api/[async|sync]/getparametricranges/v1?field_names=place_population&indexes=wiki_eng&field_text=MATCH{CITIES IN SWITZERLAND}:wikipedia_category

The Get Parametric Ranges API also allows you to set the min_score parameter for the query, to return only values for the specified field from documents 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.

Set to true to show the total number of available ranges for each field (disregarding any max_ranges limit on the request).
Default value: false.

value_details

boolean

Set to true to show additional information about the numeric values that occur in the specified field_names.
Default value: false.

Enumeration Types

This API's parameters use the enumerations described below:

sort
The criteria to use for the result display order. By default, ranges are returned in increasing numeric order.

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 option 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 option only when the document_count parameter is set to true.

number_increasing

Numeric field value (lowest number first)
Order value ranges numerically, with the lowest number first.

number_decreasing

Numeric field value (highest number first)
Order value ranges numerically, with the highest number first.

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.

Haven OnDemand uses cookies to enhance and improve the experience it provides. By continuing to use this site or pressing Continue,
we will assume that you accept receiving all cookies. If you would like to change which cookies are set, you can change your settings.