Recommendations Technical References

We will continue to support Deprecated parameters, but discourage their use because a better alternative exists

Parameter

Type

Required  

Description

bof_profile

string

The user’s ID. Not strictly required, but highly recommended. If not supplied, a session ID will be generated server-side in replacement. This is set automatically by yq.js.

content_id

string

The content ID of the current page. If the current page is non-content, this can either be omitted or set to null (ok, so it’s not strictly required).

href

string

URL of the current page. This is set automatically by yq.js.

alt_href

string

 

This will override ‘href’. Provides a way to manually set the URL of the current page.

content_type

string

 

Observed content is handled differently depending on this. If not supplied, defaults to regular articles (“content”). Supported options: [“content”, “classified”, “sponsored”].

idm

object

 

Object: IDM. This is for recording identity management / user profile information.

observe

array[object]

 

Object: Observe. Only the first object in the array is used. This object is required to index the current article.

page_hit

object

 

Object: Page Hit. This object is required to record a page hit for reporting purposes.

suggest

array[object]

 

Object: Suggest. Only the first object in the array is used. This object is required to request recommendations.

    

create_date

string

 

Deprecated: Use the Observe’s ‘create_date’ instead.

image

string

 

Deprecated: Use the Observe’s ‘image’ instead.

title

string

 

Deprecated: Use the Observe’s ‘title’ instead.

ParameterTypeRequired  Description
typestringAlways set this to “node”.
categoriesarray[string]
string
array[array[string]]
 

 

The article’s categories. The following formats are supported:

  • [“sports”, “news”]
  • “sports, news”
  • [[“sports”], [“news”]]
  • [[“basketball”, “sports”], [“local”, “news”]] – Pairs only
classified_dataobject 

 

Object: Classified.

create_datestring 

 

The publish date (and preferably time) of the article. The format must be supported by .NET’s DateTime.TryParse. Datetimes with a “Z” specifier are treated as UTC; otherwise they are treated as the domain’s local time.

descriptionstring 

 

The article’s description.

imagestring 

 

URL of the article’s primary image.

is_contentboolean 

 

Article will only be indexed if this is true. If not supplied, defaults to true.

tagsarray[string] 

 

The article’s tags.

titlestring 

 

The article’s title.

    
expiry_datestring 

 

Deprecated: We accept this parameter, but it is never used.

namestring 

 

Deprecated: Use ‘content_id’ at the top level instead.

ParameterTypeRequiredDescription
referrerstring The HTTP Referrer. This is set automatically by yq.js, which assigns the value of document.referrer.
tz_namestring 

 

The user’s timezone name. This is set automatically by yq.js, which assigns the value of timezone.olson_tz;

tz_offstring 

 

The user’s timezone offset. This is set automatically by yq.js, which assigns the value of timezone.utc_offset.

    
bof_profilestring 

 

Deprecated: Use ‘bof_profile’ at the top level instead.

hrefstring 

 

Deprecated: Use ‘href’ at the top level instead. This is set automatically by yq.js, but will be overridden by the top level href, if supplied.

namestring 

 

Deprecated: Use ‘content_id’ at the top level instead.

ParameterTypeRequired  Description
countintegerNumber of recommendations to return.

 

type

 

string

 

 

Always set this to “node”.

categoriesarray[string] 

 

If ‘strict_categories’ is set to true in Suggest Options, this list of categories will be used to restrict the content returned in the recommendations.

date_startstring 

 

Oldest publish date of content to include in recommendations.

date_endstring 

 

Newest publish date of content to include in recommendations.

domainsarray[string] 

 

List of domains to draw content from for recommendations. By default, only content from the current domain is used.

exclusionsarray[object] 

 

Object: Exclusions. List(s) of content to exclude from recommendations.

is_domain_includedboolean 

 

If false, the current domain will not be included in the list of domains to draw content from.

is_panel_builderboolean 

 

If true, recommendations will contain content ID, title and URL. Overridden by ‘panel_custom’ and ‘is_panel_detailed’.

is_panel_detailedboolean 

 

If true, recommendations will contain content ID, title, URL, image URL and description. Overridden by ‘panel_custom’.

isAllClientDomainsboolean If true, content will be drawn for recommendations from all domains (including the current domain) belonging to the client. Overridden by ‘domains’.
isUrlReturnedboolean 

 

If true, recommendations will contain URL only. Overridden by ‘panel_custom’, ‘is_panel_detailed’ and ‘is_panel_builder’.

optionsobject 

 

Object: Suggest Options. Additional options for suggest request.

panel_custom  

 

Object: Panel Custom. Use to customize the properties returned for recommendations (i.e. content ID, title, URL, etc.).

panel_typestring 

 

Identifies the type/location of panel that the recommendations will be served in. Supported options: [“home_panel”, “category_panel”, “article_panel”, “article_scroll”].

sponsored_countinteger 

 

Number of sponsored content recommendations to return. This is a subset of the ‘count’, so if ‘count’ is 6 and ‘sponsored_count’ is 2, it will return 4 “regular” recommendations and 2 sponsored content recommendations.

variantstring 

 

Specifies which recommender variant will generate recommendations. Defaults to YQ recommendations. Supported options: [“yq”, “trending”, “mostread”].

    
namestring 

 

Deprecated: Use ‘content_id’ at the top level instead.

Parameter  Type  Required Description
idstring

 

The unique user ID provided by the identity management system. This might be an email address or some random string of characters.

profileobject 
Parameter  Type  Required  Description
type  

 

 

price  

 

 

year  

 

 

is_rental  

 

 

make  

 

 

model  

 

 

condition  

 

 

vehicle_class  

 

 

address  

 

 

city  

 

 

state  

 

 

country  

 

 

zip_code  

 

 

property_type  

 

 

lot_size   number 

 

The lot size, in square-feet.

floor_size   number 

 

The floor size, in square-feet.

bedrooms   integer 

 

The number of bedrooms.

full_bathrooms   integer 

 

The number of full bathrooms.

half_bathrooms   integer 

 

The number of half bathrooms.

job_type  
Parameter  Type  Required  Description
content_idsarray[string]

 

The list of content IDs to exclude from recommendations.

domainstring

 

The domain that the content IDs belong to (all content IDs in this object have to be from the same domain).

Parameter  Type  Required  Description
disable_historyboolean 

 

If true, excludes the articles viewed by the user in the last 30 days instead of the default last 10 days.

paging_enabledboolean 

 

If true, enables the paging mechanism that allows for multiple suggest requests to be made from the same page without duplicating recommendations between them.

show_historyboolean 

 

By default and if false, articles that the user has already viewed are filtered out of recommendations. If this is true, the user’s history will not be filtered out.

strict_categoriesboolean 

 

If true, content will be restricted to categories specified by ‘categories’ in Suggest.

Parameter  Type  Required    Description
categoriesboolean 

 

If true, the categories for each article in the recommendations is returned in the results.

dateboolean 

 

If true, the publish date of each article in the recommendations is returned in the results.

descriptionboolean 

 

If true, the description for each article in the recommendations is returned in the results.

domainboolean 

 

If true, the domain of each article in the recommendations is returned in the results.

domain_nameboolean 

 

If true, the friendly domain name for each article in the recommendations is returned in the results.

imageboolean 

 

If true, the image URL for each article in the recommendations is returned in the results.

likeboolean  
readboolean 

 

If true, a boolean indicating if the user has read that article is returned in the results.

titleboolean 

 

If true, the title of each article in the recommendations is returned in the results.

urlboolean 

 

If true, the URL of each article in the recommendations is returned in the results.

    
eventboolean Deprecated: Has no effect.