Response

Overview

All responses are encoded in UTF-8 and currently come in the following formats, according to the HTTP Accept header used:

• JSON
• XML

The following conditions may occur before a request is processed, causing no response to be returned:

• If the HTTP Accept header specified a format that cannot be satisfied by the API, the HTTP response status code will be 406 — Not acceptable.
• If authentication fails for any reason, the HTTP response status code will be 401 — Unauthorized

If the API is capable of handling the request and authentication passes, a response object is returned in either XML or JSON format. The response object contains the results of the query, as well as metadata about the query that can be used either for display purposes or for further refinement of the query. The response may also contain more descriptive errors than the HTTP status errors. For more information on the response, see Response and Errors.

Both response formats contain the same major fields, which include:

• sessionId – the session ID for the current request
• elapsedQueryTime – the time spent waiting for the query to return from the search engine
• queryTime – the time the search engine spent processing the query
• totalRequestTime – the total time taken to process the request, including time to format the results
• pageCount – the total number of available pages for the current query
• didYouMeanSuggestions – suggestions for spelling corrections including the term being corrected and its suggested replacement
• recommendationLists – recommendations for databases and best bets that arebased on the user’s input
• documents – the meta documents themselves
• errors – any server, client or end-user errors
• facetFields – counts for any facet fields requested
• query – a parsed format of the query submitted after commands are applied
• rangeFacetFields – counts for any range facet fields requested

For more specific information on each field, see didYouMeanSuggestions, recommendationLists, documents, errors, facetFields, query and rangeFacetFields.

XML Format

In the XML format, the root element is response. All simple types are stored as attributes, and only complex types are stored as nested elements. Lists of elements are stored under a nested element unless the containing element only has one list. For example, the query element contains nested elements for textQueries, searchTerms, textFilters, rangeFilters, facetValueFilters, facetValueGroupFilters, facetFields, rangeFacetFields, sort params, because the query element contains more than one list. The rangeFacetField, on the other hand, does not have a nested element for ranges, because ranges is the only list on rangeFacetField. Eachrange element is stored directly on the rangeFacetField.

Example – An XML result snippet

<query
 queryString="s.rff=PublicationDate%2C1981%3A1990%2C1991%3A2000&amp;s.q=tropics&amp;s.dym=true"
 isDidYouMeanEnabled="true">
  <textQueries>
    <textQuery
     textQuery="tropics"
     removeCommand="removeTextQuery(tropics)"/>
  </textQueries>
  <didYouMeanSuggestions/>
  <recommendationLists/>
  <searchTerms/>
  <textFilters/>
  <rangeFilters/>
  <facetValueFilters/>
  <facetValueGroupFilters/>
  <facetFields/>
  <rangeFacetFields>
    <rangeFacetField
     fieldName="PublicationDate"
     removeCommand="removeFacetField(PublicationDate)">
      <range minValue="1981" maxValue="1990"/>
      <range minValue="1991" maxValue="2000"/>
    </rangeFacetField>
  </rangeFacetFields>
  <sort/>
  <params/>
</query>

JSON Format

In the JSON format, the object itself is the root. Extra nesting is avoided where possible. Objects inside arrays do not have an extra level of wrapping that contain the object name. Numbers and booleans are stored as their appropriate JavaScript types.

Example – A JSON result snippet

"rangeFacetFields":[
  {
    "fieldName":"PublicationDate_dt",
    "displayName":"PublicationDate",
    "removeCommand":"removeFacetField(PublicationDate)",
    "counts":[
      {
        "range":{
          "minValue":"1981",
          "maxValue":"1990"
        },
        "count":4570,
        "isApplied":false,
        "applyCommand":"addRangeFilter(PublicationDate,1981:1990)"
      },
      {
        "range":{
          "minValue":"1991",
          "maxValue":"2000"
        },
        "count":3817,
        "isApplied":false,
        "applyCommand":"addRangeFilter(PublicationDate,1991:2000)"
      }
    ]
  }
]