Query Response¶

Top Level Response Fields¶

• itemIds

  The list of relevant item ids on this page of the result set.

  Type: array of string

• exactMatches

  The corresponding list of whether the item was an exact match against the query.

  Type: array of boolean

• relevanceValues

  The corresponding list of relevance values for each item on this page of the result set.

  Type: array of double

• startIndex

  The index of the first item on this page of the result set.

  Type: int

• currentPageSize

  The number of items on this page of the result set.

  Type: int

• datasetSize

  The total number of items in the queried dataset.

  Type: int

• totalSize

  The total number of items in the result set.

  Type: int

• exactSize

  The number of exact matched items in the result set.

  Type: int

• facets

  Describes the facets counts for each facets criterion.

  Type: dictionary

  See: facets Response

• drillDown

  Describes the drilldown counts for each drilldown criterion. Deprecated. Use the facets request API instead.

  Type: array of dictionary

  See: drillDown

• properties

  An array of dictionaries, one for each item returned in the query response, that includes any requested changeset property values. If the query request also included a highlighting criterion, then any highlighting would be applied to the appropriate changeset property values.

  Type: array of dictionary

  See: Properties

  New in version 2.8.3.

• didYouMean

  An dictionary with one entry per didYouMean text type dimension. Each entry is a dictionary that includes the suggestions, highlighted values and information about the relevance of the suggestions.

  Type: dictionary

  See: DidYouMean

  New in version 2.9.

• highlighting

  An array of dictionaries, one for each item returned in the query response, that includes any requested changeset property values that were highlighted. This field only exists if the merge field of the highlighting request was set to none. For more information about the highlighting request, refer to Highlighting Criterion.

  Type: array of dictionary

  See: Highlighting

  New in version 2.8.4.

• indexValues

  A dictionary describing the new-form indexed values for each of the named dimensions in the indexValues request.

  Type: dictionary

  See: Index Values

  New in version 2.9.1.

• calculate

  A dictionary that lists the user-defined keys and their calculated values. The user-defined keys are specified in the calculate request.

  Type: dictionary

  See: Calculate

  New in version 3.1.0.

• values

  A dictionary describing the indexed values for each of the named dimensions in the legacy values request.

  Type: array of dictionary

  See: Values

  New in version 2.6.17.

• debug

  A dictionary describing the many aspects of the matching process, including scoring.

  Type: dictionary

  See: Debug Response

• sortBy TODO

  A dictionary listing the values used to determine sort order as specified in the sortBy criterion. This field only appears in the response when requesting the “sortBy” explain data.

  Type: array of dictionary

  See: sortBy Response

  New in version 2.8.4.

• isGrouped

  A value describing whether the response includes a groupBy result.

  Type: boolean

• legacyGroupBy

  A value describing whether the response includes a groupBy result using the legacy or new-style format. To enable the new style response format, set legacyGroupBy to true in the groupBy request criterion.

  Type: boolean

  Default: false

  See: Group By Criterion

• groups

  A dictionary describing the exact matches, item ids and relevance values for the topN items in each group of the groupBy result.

  Type: array of dictionaries

• renderParameters

  A URL encoded query string that can be passed to a template for rendering the search results. This is only present if the renderParameters request field is set to true or a dictionary.

  Type: string

  For information on how to reqeust renderParameters, refer to Render Parameters. For a description of the renderParameters response, refer to renderParmeters.

{
    "itemIds": ["10", "11", "12", "13", "14", "15", "16", "17", "18", "19"],
    "exactMatches": [true, true, true, true, true, true, true, true, true, true],
    "relevanceValues": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
    "pageSize": 10,
    "currentPageSize": 10,
    "startIndex": 0,
    "exactSize": 38,
    "totalSize": 50,
    "drillDown": [
        {
            "dimension": "bedroom",
            "ids": ["studio", "1", "2", "3", "4", "5+"],
            "exactCounts": [0, 8, 2, 38, 2, 0],
            "fuzzyCounts": [0, 8, 2, 38, 2, 0]}],
    "datasetSize": 50}

facets Response¶

The following keys appear for each facets criterion key that is present in the request.

See: Facets Criterion for a detailed description of the facets request API.

• navIds

  A list of the children who are either selected or have descendents that are selected the respect the sortBy key of the facets request.

  Type: array of string

• childIds

  A list of child ids that are options for the next level of navigation which respect the sortBy, topN, minCount and navChildIds in the facets request.

  Type: array of string

• dataIds

  The original list of dataIds from the facets request, in the same order, with invalid ids removed. Anything in the dataIds list will also be included in the data response dictionary.

  Type: array of string

• hasMore

  Indicates that the node has more children to display but that the child data was not included because of a topN restriction. This key will only be present if the list of childIds is longer than the topN request value.

  Type: boolean

• data

  A dictionary of all the requested response data for any facet id requested or related to the facet ids of the response.

  Note that the structure of data is flat. Any parentId and child node references will be included in the dictionary. To re-establish the hierarchy, use parentId and/or childIds.

  Type: boolean

{
  "facets": {
      "category": {
          "childIds": ["a", "b"],
          "data": {
              "a": {
                  "count": 20,
                  "selected": true,
                  "childIds": ["c"]
              },
              "b": {
                  "count": 5,
                  "selected": false
              },
              "c": {
                  "count": 3,
                  "parentId": "a",
                  "selected": false
              }
          }
      }
  }
}

drillDown¶

The following keys appear for each drillDown criterion that is present in the request.

See: Drilldown Criterion for a detailed description of the drilldown API.

• dimension

  Id of the dimension this drill down result refers to.

  Type: string

• ids

  Node/bucket ids.

  Type: array of string

• exactCounts

  Parallel counts based on the exact match results of the current query.

  Type: array of int

• fuzzyCounts

  Parallel counts based on all the results of the current query.

  Type: array of int

Properties¶

The response includes a key named after each changeset property requested in the query or, if no changeset properties were explicitly requested, then the response includes an entry for every changeset property of the item.

If the query request included the highlighting criterion, then any highlighting will be applied to the returned changeset property values.

The order of the dictionaries in the response array is in the same order as the items return in the query response.

The properties are stored in a disk-based database and retrieve on an as-needed basis.

New in version 2.8.3.

Sample query:

{
  "startIndex": 0,
  "pageSize": 10,
  "properties": [
                  "title",
                  "synopsis"
                ]
  "highlighting": {
    "fragmentType": "best",
    "maxFragments": 4,
    "delimiter": "...",
    "template": [ "<b>", "</b>" ],
    "fragmentSize": 100
  },
  "criteria": [
    {
      "dimension": "fulltext",
      "value": "Star Trek",
      "searchStyle": "startsWith"
    }
  ]
}

Sample response:

{
  "totalSize": 34544,
  "pageSize": 2,
  "properties": [
    {
      "title": "<b>Star Trek</b>",
      "synopsis": "Boldly going where no <b>Trek</b> has gone before...beloved crew of the <b>Starship</b> Enterprise...attend <b>Starfleet</b> Academy. But before they can even sign",
      "genres": "Science Fiction,Drama"
    },
    {
      "title": "<b>Star Trek</b> III: The Search for Spock",
      "synopsis": "Admiral Kirk has his hands full after defeating the evil Khan in<b>Star Trek</b> II:Spockisdead."
    }
  ],
  "exactSize": 2234,
  "currentPageSize": 2,
  "itemIds": [
    "17-MV",
    "1958-MV"
  ]
}

Highlighting¶

The response includes a key named after each changeset property that was highlighted. Tree dimensions are highlighted differently than text type dimensions.

The order of the dictionaries in the response array is in the same order as the items returned in the query response and is returned in the same format as the properties response field.

This field will only be present if the highlighting request merge field was set to none. For more information about the highlighting request, refer to Highlighting Criterion.

New in version 2.8.4.

Index Values¶

The response includes a key named after each dimension named in the values request. The value is in turn a dictionary with keys containing arrays of the same length as the item result set determined by the pageSize top-level request field.

Multi-values will be returned as arrays.

• id The indexed value.

• hit If the corresponding id value resulted in a match for the current

• label The name attribute of the dimension element for the given

  id that can be used to translate the id to a readable format.

See: indexValues Criterion for a description of the indexValues request API.

New in version 2.9.1.

Sample response for a 3-item response:

{
  "indexValues": {
    "genres": [
        {
          "id": [["CO"],["CD"],["DR","HR"]],
          "hit": [[false],[true],[true,false]]
          "label": [["Comedy"],["Crime Drama"],["Drama","Horror"]],
        }
     ]
  }
}

Calculate¶

The response includes a key that was defined in the calculate request. The value is in turn one or more calculated values, usually one calculated value per item in the query response.

See: Calculate Criterion for a description of the calculate request API.

New in version 3.1.0.

{
  "calcluate": {
    "distanceFromSchool": [
        "0.234", "1.3433", "10.54"
     ]
  }
}

Values¶

The response includes a key named after each dimension named in the values request. The value is an array of values, in the order of the items in the response, for the dimension.

See: Values Criterion for a description of the values request API.

Sample response:

{
  "values": {
    "genres": [
        "Comedy",
        [
          "Crime drama",
          "Drama"
        ],
        "Horror"
     ],
    "ethnicity": [
      "white",
      "asian",
      "american indian"
    ]
  }
}

sortBy Response¶

The response is an array of dictionaries, one entry for each sortBy criterion, in the order in which the criterion were specified. The first field of the response includes the type of sortBy specified in the sortBy request field builtin or dimension.

See: Sort By Criterion for a description of the sortBy request API.

• builtin The type of builtin dynamic value to used for the sort. Either builtin or dimension will be present for each sortBy response row.

  Type: string

  Values: exactMatch, relevance, id or random

• dimension The dimension whose value was used for the sort. Either builtin or dimension will be present for each sortBy response row.

  Type: string

• values The values used for the sort. This array contains an element for every item in the result set, in the same order as the result set items.

  If the dimension is a geoloc dimension then the value will the distance of the item from the geo point specified in the sortBy criterion latitude and longitude fields.

  The units (miles/kilometers) of the distance values will be in the units specified by the sortBy criterion’s distanceUnit field.

  Type: array of values

Sample response:

{
  "currentPageSize": 3,
  "datasetSize": 3,
  "exactMatches": [true, false, false],
  "exactSize": 1,
  "sortBy": [
    {
      "dimension": "Location",
      "values": [8.549, 8.549, 8.549, 9.034, 10.572, 10.572, 11.51,
                    11.51, 11.51, 11.51]
    },
    {
      "builtin": "exactMatch",
      "values": [true, true, true, false, false, false, false,
                    false, false, false]
    },
    {
      "builtin": "relevance",
      "values": [0.9996560800350993, 0.9996560800350993, 0.9996560800350993,
        0.9996365661127987, 0.999574675986841, 0.999574675986841,
        0.9995369569317102, 0.9995369569317102, 0.9995369569317102,
        0.9995369569317102]
    },
    {
      "builtin": "id",
      "values": ["933250", "933251", "933252", "877692", "985783",
                    "993906", "965193", "965194", "965195", "999564"]
    }
  ]
}

DidYouMean¶

The following keys appear in the dictionary entry for each text didYouMean dimension that appeared in the search criterion request. The key is the id of the dimension.

See: DidYouMean Criterion for a description of the Did You Mean? request API and DidYouMean for a description of the Did You Mean? web service API.

• tokenCount

  This in an informational value that indicates how many tokens (words) were discovered in the query text.

  Type: integer

• uncertainCount

  This in an informational value that indicates how many tokens (words), out of the total number of tokens (tokenCount), were not able to be provided with suggestions.

  Type: integer

• suggestions

  This is a dictionary that returns the suggested query strings. The value of up to maxSuggestions from the didYouMean request limits the number of suggestions returned.

  Suggestions are returned in order of decreasing relevance.

  Type: dictionary

  There are two keys in the dictionary:

  • value. The plain text suggested query string.
  • label. The suggested query string with replaced terms highlighted

• query

  This is a dictionary that returns the original query used for Did You Mean? as well as the version in which the replaced tokens are highlighted, if highlighting has been enabled.

  Type: dictionary

  There are two keys in the dictionary:

  • value. Original query string used for Did You Mean?
  • label. Query string with replaced terms highlighted

Sample response:

This response returns Did You Mean query suggestions for two dimensions with id “freetext” and “name” respectively.

"didYouMean": {
    "freetext": {
        "tokenCount": 2,
        "uncertainCount": 1,
        "query": {
            "value": "st marys",
            "label": "<i>st</i> <i>marys</i>"
        },
        "suggestions": [
            {
                "value": "st mary",
                "label": "st <i>mary</i>"
            },
            {
                "value": "st maria",
                "label": "st <i>maria</i>"
            },
            {
                "value": "st mark",
                "label": "st <i>mark</i>"
            },
            {
                "value": "st mar",
                "label": "st <i>mar</i>"
            }
        ]
    },
    "name": {
        "tokenCount": 1,
        "uncertainCount": 0,
        "query": {
            "value": "elementary",
            "label": "<i>elementary</i>"
        },
        "suggestions": [
        ]
    }
}

Groups¶

The following keys appear for each groupBy criterion that also specifies the topN field. Note that the field name for the response is groups.

See: Group By Criterion for a description of the groupBy request API.

• itemIds

  The list of relevant item ids for each topN item in each group.

  Type: array of array of string

• exactMatches

  The parallel array (to itemIds) that indicates whether the topN item was an exact match against the query.

  Type: array of array of boolean

• relevanceValues

  The parallel array (to itemIds) that reports the relevance values for each topN item on this page of the result set.

  Type: array of array of double

• properties

  The parallel array (to itemIds) that reports the propertiess for each topN item on this page of the result set.

  Type: array of array of double

• highlighting

  The parallel array (to itemIds) that reports the highlighting for each topN item on this page of the result set.

  Type: array of array of double

• indexValues

  The parallel array (to itemIds) that reports the indexValues for each topN item on this page of the result set.

  Type: array of array of double

Sample response:

{
  "startIndex": 0,
  "currentPageSize": 3,
  "pageSize": 3,
  "datasetSize": 33853,
  "itemIds": ["1011068", "1030677", "1001509"],
  "exactMatches": [true, true, true],
  "relevanceValues": [1, 1, 1],
  "isGrouped": true,
  "groups": {
    "itemIds": [
      ["854516", "854517"],
      ["971633", "938607"],
      ["5194685", "839126"]
    ],
    "exactMatches": [
      [true, true],
      [true, true],
      [true, true]
    ],
    "relevanceValues": [
      [1, 1],
      [1, 1],
      [1, 1]
    ],
    "indexValues": {
      "City_Id": {
        "hit": [
          [[true, false, false], [true, false, false]],
          [[true], [true]],
          [[true, false, false], [true, false, false]]
        ],
        "value": [
          [["106335-45", "126371-45", "127679-45"], ["106335-45", "126371-45", "127679-45"]],
          [["106335-45"], ["106335-45"]],
          [["106335-45", "126371-45", "127679-45"], ["106335-45", "126371-45", "127679-45"]]
        ]
      }
    },
    "properties": [
      [
        {
          "Baths": "1.0",
          "Beds": "1",
          "State_Name": "Ohio",
          "Zip_Code": "44224"
        },
        {
          "Baths": "2.0",
          "Beds": "2",
          "State_Name": "Ohio",
          "Zip_Code": "44224"
        }
      ],
      [
        {
          "Baths": "1.5",
          "Beds": "2",
          "State_Name": "Ohio",
          "Zip_Code": "44221"
        },
        {
          "Baths": "2.0",
          "Beds": "3",
          "State_Name": "Ohio",
          "Zip_Code": "44221"
        }
      ],
      [
        {
          "Baths": "2.0",
          "Beds": "3",
          "State_Name": "Ohio",
          "Zip_Code": "44224"
        },
        {
          "Baths": "1.0",
          "Beds": "1",
          "State_Name": "Ohio",
          "Zip_Code": "44224"
        }
      ]
    ]
  }
}

The the query or groupBy dimension enables legacyGroupBy then the response will include the following fields.

• itemIds

  The list of relevant item ids on this page of the result set.

  Type: array of string

• exactMatches

  The corresponding list of whether the item was an exact match against the query.

  Type: array of boolean

• relevanceValues

  The corresponding list of relevance values for each item on this page of the result set.

  Type: array of double

  See: Group By Criterion for a description of the groupBy request API.

Sample response:

{
  "currentPageSize": 3,
  "datasetSize": 3,
  "exactMatches": [true, false, false],
  "exactSize": 1,
  "groups": [
    {
      "exactMatches": [true, false, false],
      "itemIds": ["CheapHeavyCircle", "CheapLightCircle", "LightCircle"],
      "relevanceValues": [1, 0.99999999720603228, 0.99999999534338713]
    },
    {
      "exactMatches": [false, false, false],
      "itemIds": ["CheapTriangle", "HeavyTriangle", "ExpensiveLightTriangle"],
      "relevanceValues": [0.99999999860301614, 0.99999999580904841, 0.99999998789280653]
    },
    {
      "exactMatches": [false, false, false],
      "itemIds": ["Square", "ExpensiveHeavySquare", "ExpensiveSquare"],
      "relevanceValues": [0.99999999487772584, 0.99999999161809683, 0.99999999022111297]
    }
  ],
  "isGrouped": true,
  "legacyGroupBy": true,
  "itemIds": ["circle", "triangle", "square"],
  "pageSize": 10,
  "relevanceValues": [1, 0.99999999860301614, 0.99999999487772584],
  "startIndex": 0,
  "totalSize": 3
}

Debug Response¶

Transparensee Systems reserves the right to alter or remove this API in any way and at any time in the future. It provides this feature solely for debugging purposes.

See: Debug Request for a description of the debug request API.

Example:

{
  "debug": {
    "explain": {
      "10": "... LONG EXPLANATION GOES HERE ..."
    },
    "explainFuzzy": {
      "11": "... LONG EXPLANATION GOES HERE ..."
    },
    "query": "+linearScore(normalDistance=1000000,from=dist(selected=\"[3,4)\",field=bedroom_int_sndv)) #bedroom_i:[3 TO 4}",
    "queryFuzzy": "+linearScore(normalDistance=1000000,from=dist(selected=\"[3,4)\",field=bedroom_int_sndv)) #_dimensions_s:bedroom",
    "sortBy": [
      {
        "builtin": "exactMatch",
        "values": [true,false]
      },
      {
        "builtin": "relevance",
        "values": [1,1]
      },
      {
        "builtin": "id",
        "values": ["10","11"]
      }
    ],
    "time": {
      "search": 0,
      "searchFuzzy": 0,
      "count": 0,
      "page": 0,
      "total": 1
    }
  }
}

renderParmeters¶

The renderParameters response is used primarily by the Transparensee jQuery widget suite. It returns a single field, “renderParameters”.

See: Render Parameters for a description of the renderParmeters request API.

Sample responses:

{
  "renderParameters": "startIndex=0&pageSize=4&exactSize=9&totalSize=9 \
      &itemIds=CheapHeavyCircle+CheapLightCircle+CheapTriangle+ExpensiveHeavySquare \
      &exactMatches=1111"
}

{
  "renderParameters": "startIndex=0&pageSize=4&exactSize=9&totalSize=9 \
      &itemIds=CheapHeavyCircle%2CCheapLightCircle%2CCheapTriangle%2CExpensiveHeavySquare \
      &exactMatches=1111"
}