Advertiser Search Service v.2

The Advertiser Search Service is a SOAP (Simple Object Access Protocol)-based API that enables developers to find advertisers in the Commission Junction network based on desired criteria. Developers may search for advertisers by any number of criteria including keywords, country, category, targeted area, relationship status or links offered (link size or 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 Advertiser 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.

keywords

String

Optional

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

Tip: Values entered in this field search against Web site names, promotions, program URLs and keywords.

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

Query

Results

"kitchen sink"

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

"+kitchen +sink"

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

"+kitchen -sink"

Any advertiser with "kitchen" and without "sink"

"kitchen +sink"

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

 

category

String

Optional

Limits the results to advertisers 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 advertisers with 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 advertisers with 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 advertisers offering a specific link type. You may obtain a list of available link types using the Support Services.

linkSize

String

Optional

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

targetedArea

String

Optional

Limits the results to 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.

sortBy

String

Optional

Sort the results by any of the following  response fields.

  • advertiserName

  • advertiserId

  • networkRank

  • sevenDayEPC

  • threeMonthEPC

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

sortOrder

String

Optional

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

  • asc: ascending

  • desc: 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: 1000 results is the system limit for results per request. If you request a value greater than 1000, the system only returns 1000.

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

Request number

startAt value

maxResults value

Request 1

0

250

Request 2

250

250

Request 3

500

250

Request 4

750

250

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

advertisers

Array

An array of advertiser records. See the Per Record (Advertiser) table for the fields returned for each advertiser 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 (Advertiser)

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

Field Name

Value

Description

advertiserId

String

The advertiser’s CID.

clickCommission

String

The commission per click offered by the advertiser.

leadCommission

String

The commission per lead offered by the advertiser.

linkTypes

Array (Strings)

An array of strings containing the link types offered by the advertiser.

advertiserName

String

The advertiser’s name.

networkRank

String

The advertiser’s network ranking.

performanceIncentives

String

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

primaryCategoryId

String

The advertiser’s primary category ID.

primaryCategoryName

Array (Strings)

An array of strings (currently, only one string) that contains the advertiser’s primary category name.

relationshipStatus

String

The advertiser’s 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 advertiser’s 7-day EPC.

threeMonthEPC

String

The advertiser’s 3-month EPC.

Errors

Error

Description

Not Authenticated

The system could not authenticate your developer key.