All responses are encoded in UTF-8 and currently come in the following formats, according to the HTTP Accept header used:
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.
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
<range minValue="1981" maxValue="1990"/>
<range minValue="1991" maxValue="2000"/>
Example - A JSON result snippet