Search Response Vocabulary
Search responses contain the same information whether formatted as JSONP or XML, and hence use the same vocabulary. The following field definitions follow the format:
- jsonName [xml-name]
- definition
where [xml-name] is omitted if it is identical to jsonName.
Search Results
Each response contains a set of information about the set of results as a whole, including at least:
- version
- the version of the API to which the response conforms
- query
- the query provided in the request
- time
- the time at which the result set was generated, in seconds since the epoch (midnight, January 1, 1970 UTC)
- maxAge [max-age]
- the number of seconds for which the result should be considered valid
- totalResults [total-results]
- the estimated total number of results available for this query (can be used to estimate the number of pages available)
The response may also include:
- type
- the type of content requested: ALL or VIDEO
- default value: ALL
- order
- the criterion by which results are ordered: PULSE or REALTIME
- default value: PULSE
- pageNumber [page-number]
- the 1-based number of the page of results presented by the response, calculated with respect to pageSize
- default value: 1
- pageSize [page-size]
- the number of results per page, determined by the value of the limit parameter of the request
- may be omitted only if pageNumber is 1
Result
In addition to the result-set information, each response may contain a list of zero or more featured results and/or a list of zero or more organic results:
- featuredResultList [featured-result-list]
- the list of featured results returned
- in XML responses, each individual result is represented as a child <featured-result> element
- may be omitted if content=RESULTS_ONLY or no featured results were found
- resultList [result-list]
- the list of organic results returned, ordered from most relevant to least relevant with respect to the requested order
- in XML responses, each individual result is represented as a child <result> element
- may be omitted if content=FEATURED_ONLY or no organic results were found
Each member of featuredResultList or resultList contains at least:
- displayUrl [display-url]
- URL of the result, as it should be displayed to the user
- redirectUrl [redirect-url]
- URL that must be used to navigate to the result, e.g. in response to the user clicking on the result
- source
- Human-friendly name of the site that published the result
- trackingUrl [tracking-url]
- URL that must be accessed to indicate that the result has been presented to a user
and may also contain zero or more of:
- type
- type of the result: WEB_PAGE or VIDEO
- default value: WEB_PAGE
- title
- title of the result
- snippet
- representative portion of text from the result, with query terms highlighted by
<b>…</b> and with special characters encoded as character entity references so that it can be directly embedded in HTML content or used to set an HTML element’s innerHTML.
- thumbnail
- representative image of the result
- this field contains subfields: see Image below
- mediaDuration [media-duration]
- the duration in seconds of the media (video) to which the result refers
- firstShare [first-share]
- information about the first known share of the result
- this field contains subfields: see First Share below
- sharesList [shares-list]
- a set of collections of information about the shares of the result on a particular service
- the members of this field contain subfields: see Shares below
First Share
If present, the firstShare result field contains at least:
- user
- information about the user who first shared the result
- this field contains subfields: see User below
- time
- the time at which the result was first shared, in seconds since the epoch (midnight, January 1, 1970 UTC)
and may also contain:
- comment
- a comment made by the user as part of the share
Shares
Each member of the set of shares provided with a result contains:
- service
- the service to which the shares member refers
- an identifier from the set of published service identifiers (see Service below)
- total
- the total number of times the result was observed to be shared by users of service.
Service
The following identifiers identify those services about which OneRiot currently publishes sharing information. This is not a complete list of the services and sources of information OneRiot uses to discover and rank search results.
- TWITTER
- Twitter
- DIGG
- Digg
Developers should expect this list to expand in the future without notice, and should therefore handle new values gracefully.
User
These subfields are used to identify and describe a user. Any field that refers to a user will contain at least:
- service
- the service to which the user belongs
- must be an identifier from the set of published service identifiers: see Service above
- id
- a string that uniquely identifies the user with respect to service
and may also contain:
- image
- an image that represents the user on the service
- this field contains subfields: see Image below
Image
These subfields are used to identify and describe an image. Any field that refers to an image will contain at least:
- url
- the URL from which the image data can be obtained
and may also contain:
- width
- the width of the image in pixels
- height
- the height of the image in pixels
