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).

/1/api/[async|sync]/getparametricranges/v1?field_names=place_population&indexes=wiki_eng&ranges=FIXED{.,1E6,5E7,1E8,.}:place_population

This returns information about values in the wiki_eng text index place_population field in the ranges:

  • Less than 1 million
  • 1 to 50 million
  • 50 to 100 million
  • More than 100 million

The response is:

{
   fields: [
      {
         name: "place_population",
         value_ranges: [
            {
               upper_bound: 1000000,
               count: 141
            },
            {
               lower_bound: 1000000,
               upper_bound: 50000000,
               count: 65
            },
            {
               lower_bound: 50000000,
               upper_bound: 100000000,
               count: 2
            },
            {
               lower_bound: 100000000,
               count: 4
            }
         ]
      }
   ]
}

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:

/1/api/[async|sync]/getparametricranges/v1?field_names=place_population&field_names=lat&indexes=wiki_eng&ranges=FIXED{.,1E6,5E7,1E8,.}:place_population+FIXED{0,30,60,90}:lat

This example returns the same ranges as the previous example for the place_population field, and also the ranges 0-30, 30-60, and 60-90 for the lat field.

{
   fields: [
      {
         name: "place_population",
         value_ranges: [
            {
               upper_bound: 1000000,
               count: 141
            },
            {
               lower_bound: 1000000,
               upper_bound: 50000000,
               count: 65
            },
            {
               lower_bound: 50000000,
               upper_bound: 100000000,
               count: 2
            },
            {
               lower_bound: 100000000,
               count: 4
            }
         ]
      },
      {
         name: "lat",
         value_ranges: [
            {
               lower_bound: 0,
               upper_bound: 30,
               count: 79
            },
            {
               lower_bound: 30,
               upper_bound: 60,
               count: 391
            },
            {
               lower_bound: 60,
               upper_bound: 90,
               count: 5
            }
         ]
      }
   ]
}

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:

/1/api/[async|sync]/getparametricranges/v1?field_names=place_population&indexes=wiki_eng&value_details=true

This example does not include the ranges parameter, but the value_details returns the minimum and maximum values for the field, which allows you to determine the appropriate ranges to generate.

{
   fields: [
      {
         name: "place_population",
         value_details: {
            count: 212,
            sum: 7334058802,
            mean: 34594616.99,
            minimum: 15,
            maximum: 3812366000
         },
         value_ranges: [
            {
               count: 212
            }
         ]
      }
   ]
}

Sort and Limit Results

By default, the API returns the result ranges in increasing numeric order. You can use the sort parameter to change the range order. For example:

/1/api/[async|sync]/getparametricranges/v1?field_names=place_population&indexes=wiki_eng&ranges=FIXED{.,1E6,5E7,1E8,.}:place_population&sort=number_decreasing

This API call returns the specified ranges in order of decreasing numeric value.

{
   fields: [
      {
         name: "place_population",
         value_ranges: [
            {
               lower_bound: 100000000,
               count: 4
            },
            {
               lower_bound: 50000000,
               upper_bound: 100000000,
               count: 2
            },
            {
               lower_bound: 1000000,
               upper_bound: 50000000,
               count: 65
            },
            {
               upper_bound: 1000000,
               count: 141
            }
         ]
      }
   ]
}

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).

/1/api/[async|sync]/getparametricvalues/v1?field_names=place_population&indexes=wiki_eng&ranges=FIXED{1E6,2E7,3E7,4E7,5E7,6E7,7E7,8E7,9E7,1E8,.}:place_population&max_ranges=5&sort=document_count&total_ranges=true

{
   fields: [
      {
         name: "place_population",
         total_ranges: 10,
         value_ranges: [
            {
               lower_bound: 1000000,
               upper_bound: 20000000,
               count: 61
            },
            {
               lower_bound: 100000000,
               count: 4
            },
            {
               lower_bound: 30000000,
               upper_bound: 40000000,
               count: 2
            },
            {
               lower_bound: 20000000,
               upper_bound: 30000000,
               count: 1
            },
            {
               lower_bound: 40000000,
               upper_bound: 50000000,
               count: 1
            }
         ]
      }
   ]
}

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.

/1/api/[async|sync]/querytextindex/v1?text="*"&indexes=wiki_eng&field_text=NRANGE{1000000,50000000}:place_population&print_fields=place_population

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:

/1/api/[async|sync]/getparametricranges/v1?field_names=place_population&text=capital city&ranges=FIXED{.,1E6,5E6,1E7,.}:place_population

The API finds documents that match the query, and for these documents, Haven OnDemand returns information about the values in the place_population field, organized in the specified ranges.

{
   fields: [
      {
         name: "place_population",
         value_ranges: [
            {
               upper_bound: 1000000,
               count: 125
            },
            {
               lower_bound: 1000000,
               upper_bound: 5000000,
               count: 38
            },
            {
               lower_bound: 5000000,
               upper_bound: 10000000,
               count: 13
            },
            {
               lower_bound: 10000000,
               count: 19
            }
         ]
      }
   ]
}

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.

Synchronous
https://api.havenondemand.com/1/api/sync/getparametricranges/v1
Asynchronous
https://api.havenondemand.com/1/api/async/getparametricranges/v1
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
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_ranges
number The maximum number of ranges to return for each matched field name. This parameter might be capped by your index flavor. Default value: 100.
min_score
number The minimum percentage relevance that results must have to the query to return. Default value: 0.
ranges
string The ranges to use to partition the numeric values for each field in the results. Default value: .
sort
enum The criteria to use for the result display order. By default, ranges are returned in increasing numeric order. Default value: number_increasing.
text
string The query text. See Boolean and Proximity Operators. Default value: *.
total_ranges
boolean 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.

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 Ranges Response {
fields ( array[Field] ) Matched parametric fields.
warnings ( array[Warnings] , optional)
}
Field {
name ( string , optional)
total_ranges ( integer , optional) The total number of ranges that contain values (disregarding any max_ranges limit on the request).
value_details ( Field-Value-Details , optional)
value_ranges ( array[Field-Value-Range] , optional)
}
Field-Value-Details {
count ( integer , optional) The total number of numeric values in this field for the matched documents.
sum ( number , optional) The sum of all the numeric values in this field for the matched documents.
mean ( number , optional) The mean of all the numeric values in this field for the matched documents.
minimum ( number , optional) The smallest value in this field for the matched documents.
maximum ( number , optional) The largest value in this field for the matched documents.
}
Field-Value-Range {
lower_bound ( number , optional) The lower bound for values in this range (inclusive). If this value is not present, there is no lower bound (open-ended range).
upper_bound ( number , optional) The upper bound for values in this range (exclusive). If this value is not present, there is no upper bound (open-ended range).
count ( integer , optional) The number of values in this range that exist in this field.
}
Get Parametric Ranges 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-details": {
            "type": "object",
            "properties": {
                "count": {
                    "type": "integer",
                    "minimum": 0
                },
                "sum": {
                    "type": "number"
                },
                "mean": {
                    "type": "number"
                },
                "minimum": {
                    "type": "number"
                },
                "maximum": {
                    "type": "number"
                }
            }
        },
        "field-value-range": {
            "type": "object",
            "properties": {
                "lower_bound": {
                    "type": "number"
                },
                "upper_bound": {
                    "type": "number"
                },
                "count": {
                    "type": "integer",
                    "minimum": 0
                }
            }
        },
        "field": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string"
                },
                "total_ranges": {
                    "type": "integer",
                    "minimum": 0
                },
                "value_details": {
                    "$ref": "#/definitions/field-value-details"
                },
                "value_ranges": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/field-value-range"
                    },
                    "minItems": 0,
                    "uniqueItems": true
                }
            }
        }
    },
    "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/getparametricranges/v1
/api/api-example/1/api/sync/getparametricranges/v1
Examples
See this API for yourself - select one of our examples below.
Get Parametric Ranges
Get range information for the place population field on Wikipedia
Get Parametric Ranges
Get sorted ranges and details for European country populations
Parameters
Required
Name Type Value
field_names
array
Add another value
Optional
Name Type Value
field_text
string
indexes
array
max_ranges
number
min_score
number
ranges
string
sort
enum
text
string
total_ranges
boolean
(Default: False)
value_details
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


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.