Link Search Service v.2

The Link Search Service is a SOAP (Simple Object Access Protocol)-based API that enables developers to find links in the Commission Junction network based on desired criteria. Developers may search for links by any number of criteria including keywords, country, category, targeted area, relationship status (with the advertiser), link size or link type. Refer to the following sections of this topic for more specific information.

Note: Refer to https://linksearch.api.cj.com for the most recent version of the Link Search Service WSDL. The WSDL provides all the programmatic information you need to use this API. The hand-edited version provides the information in a readable format; however, to ensure maximum compatibility with the system, use the AXIS version when developing your application.

Request Parameters

Refer to the following table for a list of the required and optional request parameters. All parameter names and values are case sensitive.

Important: You must provide all required parameters and at least one of the optional parameters. Submitting an empty request does not return all possible results; an empty request returns zero results.

Parameter Name

Value

Req?

Description

developerKey

String

Required

Your developer key obtained from the Web Services Developer Site.

token

String

Optional

Not currently used.

websiteId

String

Required

This value is your Web site ID (PID), which enables the system to generate the appropriate link code in the response. The PID must match the Web site PID which you used to register for the developer key (passed in the developerKey parameter).

advertiserIds

String

Optional

Limits the results to a set of particular advertisers (CIDs) using one of the following four values.

  • CIDs: You may provide list of one or more advertiser CIDs, separated by commas, to limit the results to a specific sub-set of merchants.

  • Empty String: Leaving this field blank returns results for nonjoined advertisers only. We recommend that you complete this field blank.

Note: Empty String for advertiserIds is currently  behaving the same as using  the nonjoined value. We will correct this in a future release.

  • joined: This special value (joined) restricts the search to advertisers with which you have a relationship.

  • notjoined: This special value (notjoined) restricts the search to advertisers with which you do not have a relationship.

keywords

String

Optional

This value restricts the search results based on keywords found in the link's name or description. You may use simple Boolean logic operators (+, -) to obtain more relevant search results. By default, the system assumes basic OR logic.

Tip: Values entered in this field search against advertiser names, link descriptions, link names and keywords.

The examples below illustrate how the boolean operators affect search results.

Query

Results

"kitchen sink"

Any link with the word "kitchen" or "sink"

"+kitchen +sink"

Any link with the words "kitchen" and "sink"

"+kitchen -sink"

Any link with "kitchen" and without "sink"

"kitchen +sink"

All the links with the word "sink"; if they also contain "kitchen", it increases the link's relevancy.

 

category

String

Optional

Limits the results to links in a specific sub-category. You may obtain a list of available categories using the Support Services.

Important: The system does not support searching top-level categories. You must choose a specific sub-category in which to search. For example, if you want links for medical equipment, you must use Equipment (the sub-category) as the value of the category parameter.

Tip: Use a combination of sub-category and keyword to obtain more precise search results. For example, to find links for medical equipment, try Equipment (the sub-category) as the value of the category parameter and Medical as the value of the keyword parameter.

linkType

String

Optional

Limits the results to links of a specific link type. You may obtain a list of available link types using the Support Services.

linkSize

String

Optional

Limits the results to links with a specific link size. You may obtain a list of available link sizes using the Support Services.

language

String

Optional

Limits the results to links offered in a specific language. You may obtain a list of available languages using the Support Services.

If you do not provide a value for this parameter, the system assumes the English language ('en').

serviceableArea

String

Optional

Limits the results to links offered by advertisers with a specific targeted area or targeted areas. Separate multiple values with a comma. You may obtain a list of available countries using the Support Services.

promotionType

String

Required if using startDate or endDate

Limits the results to link of the specified promotion type.  You must specify a value for this parameter is you use the startDate or endDate parameters. Acceptable values include the following.

  •  coupon

  •  sweekpstakes

  •  product

  •  sale

  •  free shipping

  •  seasonal link

startDate

Date

Optional

Specifies the start date of the associated promotion. You must enter dates in the MM/DD/YYYY format.

Leaving this field blank returns promotions with any start date.

endDate

Date

Optional

Specifies the end date of the associated promotion. You must enter dates in the MM/DD/YYYY format, or enter the value Ongoing to specify a promotion with no end date.

Leaving this field blank returns promotions with any end date.

sortBy

String

Optional

Sort the results by any of the following response fields.

  • linkId

  • advertiserName

  • linkDestination

  • linkType

  • creativeWidth

  • creativeHeight

  • advertiserId

  • promotionStartDate

  • promotionEndDate

  • category

If you do not provide a value for this parameter, the default sort is by relevance.

sortOrder

String

Optional

Specifies the order in which the results are sorted; the following  values are acceptable.

  • asc: ascending

  • dec: descending (default value)

startAt

String

Optional

Specifies the first record to return in the request. The first record is 0. Leaving this parameter blank assigns a default value of 0.

maxResults

String

Optional

Specifies the number of records to return in the request. Leaving this parameter blank assigns a default value of 10.

Note: 100 results is the system limit for results per request. If you request a value greater than 100, the system only returns 100.

The following table provides an example of how to use startAt and maxResults values to obtain a total of 100 results, with 25 results at a time.

Request number

startAt value

maxResults value

Request 1

0

25

Request 2

25

25

Request 3

50

25

Request 4

75

25

For more information refer to the forums at the Web Services Developer Site (http://webservices.cj.com).

Response Fields

The response includes information about the general response, as well as specific information for each record in the response. All parameter names and values are case sensitive.

General

The response includes the following information about the overall set of results in the response.

Field Name

Value

Description

links

Array

An array of link records. See the Per Record (Link) table for the fields returned for each link record in the response.

totalResults

Integer

The total number of matching results in the index, regardless of the number of results in the actual response (the value of the maxResults parameter).

Per Record (Link)

The response includes the following fields for each record (i.e., link).

Field Name

Value

Description

advertiserId

String

The advertiser's CID.

clickCommission

String

The commission per click offered by the advertiser.

creativeHeight

String

The height (in pixels) of the link.

creativeWidth

String

The width (in pixels) of the link.

leadCommission

String

The commission per lead offered by the advertiser.

linkCodeHtml

String

The link code (in HTML).

Note: This field is blank for advertisers with which you do not have a relationship (nonjoined).

linkCodeJavascript

String

The link code (in JavaScript).

Note: This field is blank for advertisers with which you do not have a relationship (nonjoined).

Note: This field is blank for advanced links.

linkDestination

String

The link's destination URL.

linkDescription

String

The link's description.

linkId

String

The link ID.

linkName

String

The link name.

linkType

String

The link type.

advertiserName

String

The advertisers name.

networkRank

String

The advertisers network ranking.

performanceIncentives

String

Whether or not the advertiser offers performance incentives. This value is Yes if they do, or No if they do not offer incentives.

promotionType

String

The associated promotion type.

promotionStartDate

TimeStamp

The associated promotion start date.

promotionEndDate

TimeStamp

The associated promotion end date.

relationshipStatus

String

The advertisers relationship status with a publisher. This value can be either joined or notjoined.

saleCommission

String

The commission per sale offered by the advertiser.

sevenDayEPC

String

The link's 7-day EPC.

threeMonthEPC

String

The link's 3-month EPC.

Errors

Error

Description

Not Authenticated

The system could not authenticate your developer key.