Publisher API

This document describes how to use the Adwe Publisher API, create a valid request and interpret the response.


You can retrieve results for a particular Ad request by sending an HTTP 1.1 GET request to its URI. You pass in the details of the request as query parameters. The format of the valid request looks like this:[parameters].

Three query parameters are required with each Ad request:

  • Provider key - feed identifier, specified by pid query parameter.
  • Query/niche - used to call Ads, specified by q query parameter.
  • IP address - of the end user, specified by ip query parameter.

Other query parameters are optional and some of them might have default values. To speedup the whole process of getting the result you might to want to set Accept-Encoding: gzip in request HTTP header. Table below shows parameters which will be considered in request, other parameters, which are not listed below will be discarded.

Parameter Meaning Notes
pid Provider key.
  • Your Provider key identifies your feed and provides you with API access, quota, and reports.
  • Obtain your Provider Key from publisher account.
  • This parameter is required.
q Search context.
  • Query/niche to look for ads results.
  • Limited to 256 characters.
  • This parameter is required.
ip IP address of the end user for whom the API call is being made.
  • User IP address in IPv4 format.
  • Limited to 45 characters.
  • This parameter is required.
user_agent Browser User Agent header field.
  • Browser User Agent.
  • Encoded obeying RFC3986 (raw_url_encode).
geo Country code ISO 3166-1 alpha-2.
ref Identifies source for which results are being requested.
  • HTTP referer,domain name, application name.
  • Ex. (, (, (clash of clans).
  • Encoded obeying RFC3986 (raw_url_encode).
num Number of ads to return.
  • Number of requested ads.
  • Default value: "6".
adultFilter Specifies if adult Ads are to be returned.
  • Valid values: (0, 1).
  • If "1" adult Ads will not be considered.
  • Default value: "1".
test Specifies if request is test.
  • Valid values: (0, 1).
  • If "1" request will be treated as test.
  • Default value: "0".
output Data format for the response.
  • Valid values: (json).
  • UTF-8 encoded.
  • Default value: "json".


In case of successful request (HTTP response code is 200 OK) response should be retrieved in specified format. In valid response, you might find properties specified in the table bellow. Response should be considered correct when retrieved status property is success. In any other case, response should be rejected. In valid result you will find array of objects with mandatory properties title, link and cpc. Other attributes are optional.

Property Type Meaning Notes
status string Response status.
  • Valid values: ("success", "failed").
ads array object Array of Ad objects.
  • Array of Ad objects with num elements (specified in request).
ad.title string Ad title.
  • Limit not specified.
ad.description string Ad description.
  • Limit not specified. string Ad link.
  • Limit not specified.
ad.hostname string Ad host name.
  • Limit not specified.
ad.image string Ad image URL.
  • Limit not specified.
ad.price string Ad product price.
  • Limit not specified.
ad.cpc float Ad Cost per Click.
  • Limited to four decimal places.

PHP integration

Implementing Adwe Publisher API using PHP Adwe Client script is shown below. Array with request parameters should be passed to AdweClient constructor and using getAds() method array of ads will be returned.

Constructor expects two arguments, first one is array of request parameters and second one is HTTP connection Accept-Encoding header which is by default */*.

Method getAds() may return array of arrays or array of objects which represent ads depending on provided format parameter "array" or "object".