Difference between revisions of "API setting"

Latest revision as of 12:23, 24 July 2023

1 PHP SDK
2 API authorization with a Bearer Token
3 API authorization with a signature
4 Campaign Statistics
5 Statistics on sites in the advertiser's account
6 Change the multiplier for statistics on sites in the advertiser's account
7 Statistics on all campaign materials
8 Material statistics
9 Creating an advertising campaign
10 Editing ad campaigns
11 List of campaign advertising campaign
12 Archiving an advertising campaign
13 Receiving codes for CPA campaigns
14 Getting a list of categories for a given filter
15 Getting the list of ad formats
16 Getting the list of platforms
17 Getting Browser List
18 Getting a list of conversion notifications for the CPA
19 Getting a list of ages
20 Getting a list of countries
21 Getting a list of regions
22 Getting a list of cities
23 Getting a list of devices
24 Getting a list of browser languages
25 Creating advertising agency clients
26 Editing advertising agency clients
27 Getting a list of advertising agency clients
28 Archiving advertising agency clients
29 Tying a client to an advertising agency
30 Detaching a client from an advertising agency
31 Customer account replenishment
32 Creating advertisements
33 Update ad data
34 Archiving advertisements
35 Getting a list of advertisements
36 Getting a list of banner sizes
37 Getting the list of countries
38 Getting a list of regions for a given filter
39 Get a list of available payment systems
40 Download media files
41 Get the current server time
42 Statistics for Webmasters
43 Money transfer for subsidiary accounts of the agency

PHP SDK

Install from github: https://github.com/kadam-official/php-sdk
Install from composer:

       composer require kadam/php-sdk

API authorization with a Bearer Token

To authorize in the system via API with Bearer Token you need to add to your request the "Authorization" header with "Bearer X" value where "X" is your personal token. You can get the token by asking your manager. The lifetime of token is not limited. You can change your token in the settings of your personal account.

API authorization with a signature

To access the API, you will need a user ID (app_id) and a signature (signature). Calling different methods is carried out using queries on this template:


        api.kadam.net?%action%.%method%?%params%

        % action% - what are we turning to
        % method% - type of treatment
get - get
put - write
post - update
delete - delete
        % params% - request parameters

        required parameters% params%

        app_id - user id
        signature - signature

Example:


       [GET] http://api.kadam.net/campaigns.get?app_id=%app_id%&signature=%signature%

or


       [GET] http://api.kadam.net/campaigns?app_id=%app_id%&signature=%signature%
       [GET] - http access method

Signature (signature) is created using a temporary token (access_token), which can be obtained using the app_id and secret key parameters.
Parameters app_id (user ID) and the key "secret key" are available on request to support.
Getting a token:


       [GET] http://api.kadam.net/auth.token?app_id=%app_id%&secret_key=%key%
       -> {“access_token”: “...”}

Generating signature for the [GET] method:


       md5 ( %sort_params% . %access_token% )
       %sort_params% - all parameters passed (except signature) are sorted by name

Example:


       app_id=1&campaign_id=3…
       [PUT] http://api.kadam.net/campaigns?signature=%signature%
       +post fields -> %params%

Example for php. Getting a list of campaigns:


       <?
        $your_secret_key = "jqhwekq8734quo37o498q3p498qp34";
       $your_app_id = 1;
       $auth_url = "http://api.kadam.net/auth.token?app_id={$your_app_id}&secret_key={$your_secret_key}";
       $auth = file_get_contents($auth_url);
       $auth = json_decode($auth, true);

       if ( !is_array( $auth ) || !isset( $auth['access_token'] ) ) {
           die( 'something wrong! ' . print_r( $res, true ) );
       }

       $token    = $auth['access_token'];
       $params = array(
	    'client_id' => $your_app_id,
        'app_id' => $your_app_id,
       );

       ksort( $params );

       $result = array ();
       foreach( $params as $key => $value ) {
           $result[] = $key . '=' . urlencode( $value );
       }
       $params = implode( '&', $result );
       $signature = md5( $params . $token );

       $campaign_url = 'http://api.kadam.net/ads.campaigns.get?' . $params . '&signature=' . $signature;

       $campaigns = file_get_contents($campaign_url);
       $campaigns = json_decode($campaigns, true);

       if ( !is_array( $campaigns ) || !isset( $campaigns['response'] ) ) {
           die( 'something wrong! ' . print_r( $campaigns, true ) );
       }
       
       print_r($campaigns);

Campaign Statistics

To get campaign statistics, use the method ads.stats.campaign.get

Parameters	Values	Optional attributes
campaigns	One or some campaign's id	int (numeric value), required parameter
group	Group by: date - by dates campaign - by campaigns	string, listed with a comma, required parameter
date_from	The starting date of the statistics to display. Different date formats are used for different parameter period values: day: YYYY-MM-DD, example: 2011-09-27; month: YYYY-MM, example: 2011-09	required parameter, string
date_to	The final date of the displayed statistics. Different date formats are used for different parameter period values: day: YYYY-MM-DD, example: 2011-09-27; month: YYYY-MM, example: 2011-09	required parameter, string
sort	One or some parameters for sorting data, listed with a comma.	optional parameter
limit	Number of rows returned	optional parameter, int (numeric value)
offset	Offset on returned rows (use with limit parameter)	optional parameter, int (numeric value)

Result:
Returns an object with data


{
   "response":{
      "count": %number rows returned%,
      "items":[
         {
            “date” // date; if group by date
            "id" // id campaign; if group by campaign
            "views"
            "clicks"
            "conversions"
            "rejections"
            "holds"
            "moneyOut" // spent
            "moneyIn" // income
            "ctr" 
            "cpm"
            "cpc"
         }
      ]
   }
}

Sorting

Sort Ascending

 sort = {parameter}
Example: api.kadam.net?sort=views

Sort descending

 sort = - {parameter}
Example: api.kadam.net?sort=-views

Sort by several parameters

 sort = {parameter1}, - {parameter2}, {parameter3}
Example: api.kadam.net?sort=views,-clicks,leads

Statistics on sites in the advertiser's account

Statistics on sites in the advertiser's account references statistics on views and clicks on the site in the context of each campaign.
To get statistics on sites, use the ads.stats.campaign.placement.get method (GET request)

Parameters	Value	Additional attributes
campaigns	One or some id campaigns, listed with a comma	string; mandatory parameter
date_from	Start date of the statistics output.	string, mandatory parameter, format YYYY-MM-DD (example: 2017-05-15), filter parameter
date_to	The end date of the statistics output.	string, mandatory parameter, format YYYY-MM-DD (example: 2017-05-15), filter parameter
sort	One or some parameters for sorting data, listed with a comma.	optional parameter
limit	Number of rows returned	optional parameter, int (numeric value)
offset	Offset on returned rows (use with limit parameter)	optional parameter, int (numeric value)
signature	Signature (generated using a time token, see above)	required parameter, string
app_id	user id	required parameter, int (numeric value)

Result:
Returns an object with data, example:


{
   "response":{
      "count": %количество возвращаемых элементов%,
      "items":[
         {
            "id" // id campaign
            "placement" // id placement
            "views"
            "clicks"
            "conversions"
            "rejections"
            "holds"
            "moneyOut"
            "moneyIn"
            "ctr"
            "cpm"
            "cpc"
            "prelandvisit"
            "prelanduseful"
            "prelandscroll"
            "landvisit"
            "landuseful"
            "landscroll"
            "blackList"
            "multiplier" // stake multiplier
         }
      ]
   }
}

Sorting

Sort Ascending

 sort = {parameter}
Example: api.kadam.net?sort=views

Sort descending

 sort = - {parameter}
Example: api.kadam.net?sort=-views

Sort by several parameters

 sort = {parameter1}, - {parameter2}, {parameter3}
Example: api.kadam.net?sort=views,-clicks,leads

Filtration

 {parameter} = {value}
Examples:
api.kadam.net?attr=10
api.kadam.net?attr=string
api.kadam.net?attr=string&date_from=01.05.2016&date_to=01.07.2016

Change the multiplier for statistics on sites in the advertiser's account

To change the multiplier for site statistics, use the ads.stats.campaign.placement.put method (GET request). Bearer-token authorization required. Parameters (all are required):

app_id - user id, numeric value (int)
campaign_id - campaign id, numeric value (int)
multiplier - new multiplier value, numeric value (float)
placement - place id, numeric value (int)

The block and macros parameters in the account are not displayed, they can be obtained through the method described in the paragraph "Statistics by sites in the advertiser's account".

Statistics on all campaign materials

To get statistics on all campaign materials, use the ads.stats.creative.get method

Parameters	Value	Additional attributes
campaigns	One or some id campaigns, listed with a comma	string; mandatory parameter if not set creatives
creatives	One or some id creatives, listed with a comma	string; mandatory parameter if not set campaigns
group	Group by: date - by dates creative - by creatives	string, listed with a comma, required parameter
date_from	The starting date of the displayed statistics. Different date formats are used for different values of the period parameter: 1. day: YYYY-MM-DD, Example: 2011-09-27 2. month: YYYY-MM, example: 2011-09	required parameter, string
date_to	End date of output statistics. Different date formats are used for different values of the period parameter: 1. day: YYYY-MM-DD, Example: 2011-09-27 2. month: YYYY-MM, example: 2011-09	required parameter, string
sort	One or some parameters for sorting data, listed with a comma.	optional parameter
limit	Number of rows returned	optional parameter, int (numeric value)
offset	Offset on returned rows (use with limit parameter)	optional parameter, int (numeric value)

Result:
Returns an object with data


{
   "response":{
      "count": %количество возвращаемых элементов%,
      "items":[
         {
            "date" // date; returned if group by dates
            "id" // id creative; returned if group by creatives
            "views"
            "clicks"
            "conversions"
            "rejections",
            "holds"
            "moneyOut" // spent
            "moneyIn" // income
            "ctr"
            "cpm"
            "cpc"
         }
      ]
   }
}

Material statistics

For statistics on the material, use the method ads.analytic.material.get

Parameters	Value	Additional attributes
material_id	material id	int (numeric value), required parameter
period	Method for grouping data by date: 1. day - statistics by day; 2. month - statistics by months; Temporary restrictions are set by date_from and date_to parameters	required parameter, string
date_from	The starting date of the displayed statistics. Different date formats are used for different values of the period parameter: 1. day: YYYY-MM-DD, Example: 2011-09-27 2. month: YYYY-MM, example: 2011-09	required parameter, string
date_to	End date of output statistics. Different date formats are used for different values of the period parameter: 1. day: YYYY-MM-DD, Example: 2011-09-27 2. month: YYYY-MM, example: 2011-09	required parameter, string

Result:
Returns an object with data


{
response: {
count:% total items%
items: {
date
shows
clicks
ctr
cpm
money
                       }
                  }
}

Creating an advertising campaign

To create a new advertising campaign, use the ads.campaigns.put
method Fifty (50) campaigns can be created with a single request.

Parameters	Value	Additional attributes
data </td>	a serialized JSON array of objects describing the campaigns being created. See the client_specification object description below.	required parameter, string
client_specification
app_id	user id	required parameter, int (numeric value)
client_id	id of the client in whose advertising account the campaign will be created. It can also take the value app_id (itself)	required parameter, int (numeric value)
ad_format	Ad Format: 10 - Teaser; 20 - Banner; 30 - Push Notifications; 40 - Clickunder; 60 - Contextual	required parameter, int (numeric value)
cost_type	Payment method: 0 - CPC; 1 - CPA; 2 - CPM	required parameter, int (numeric value)
name	campaign name	required parameter, string
Link_url	link to the advertised object in the format: http: //yoursite.cоm	required parameter, string
pushType	Push type: 1 - On-site Push; 2 - Classic; 4 - In-app push;	int (numeric value) example: "pushType: 1,2,4"
real_url	link to the real domain of the advertised object in the format: http: //yoursite.cоm	required parameter, string
sex	Gender: 3 - any; 2 - male; 1 - female	required parameter, int (numeric value)
age	The age of the target audience. Age category number from 1 to 6 (up to 17, 18-25, 26-34, 35-49, 50-60, over 61)	required parameter, a sequence of numbers separated by a comma
countryTarget	Countries id: /ads.targeting.countries.get	required parameter array [country_id => [ bid => 0.1, leadCost => 0.2 ] ]
regionTarget	ID regions: /ads.targeting.regions.get	required parameter, a sequence of numbers separated by a comma
cityTarget	ID cities: /ads.targeting.cities.get	required parameter, a sequence of numbers separated by a comma
cpa_mode	Type of conversion notifications for CPA: /ads.targeting.modes.get	int (numeric value), mandatory for CPA campaigns
categories	category IDs: /data.categories.get?ad_format =%	required parameter, a sequence of numbers separated by a comma
tags	keyword targeting	required parameter, a sequence of keywords separated by a comma: [“key1”, “key2”, .., “keyN”] Keywords with price. Only for payment - for clicks or for views: {“key1”: “cost”, “key2”: “cost”, .., “keyN”: “cost”} cost - float example: "data [tags] [qwerty]: 1" is the qwerty keyword with a 1rub rate.
day_limit	Daily limit in rubles. For all types except clickunder	positive number
all_limit	Total limit in rubles. For all types except clickunder	positive number
click_limit	Maximum count. transitions per day. For all types except clickunder. For views and clicks.	positive number
conversion_limit	Maximum count. conversions per day. For all types except clickunder. Only for CPA	positive number
adult_content	presence of adult content in the advertising campaign: 0 - No; 1 - Yes	optional parameter, int (numeric value), default 0
adult_site	Display campaign ads on adult content sites: 0 - No; 1 - Yes	optional parameter, int (numeric value), default 0
time_show	Time Targeting: & nbsp; & nbsp; * - display in any hours and days of the week & nbsp; & nbsp; {} is an array, where the key is the name of the day of the week ["Sn", "Mn", "Tu", "Wd", "Th", "Fr", "Sa"]: & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; {} - ‘mn’: ‘*’ - all watches are weekly & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; {} - ‘mn’: [0, .., 23] - hours, separated by commas	optional parameter, * default
platforms	platform targeting: /data.platforms	comma separated numbers
browsers	browser targeting: /data.browsers	comma separated numbers
black_list	black list of sites where ads will not be shown	comma separated site ID number sequence
white_list	white list of sites where ads will not be shown	comma separated site ID number sequence
black_list_ip	ip lock	sequence of ip addresses separated by a comma or an array
unique_day_count	frequency of material shown to one user (times)	positive number
unique_days	frequency of advertising material shown to one user (days)	positive number
deviceTarget	ID devices: /ads.targeting.devices.get	sequence of numbers separated by a comma
langTarget	ID browser languages: /ads.targeting.langs.get	sequence of numbers separated by a comma

Result:
Returns an array of responses to queries in the data array. The corresponding object in the output array contains the id of the created campaign, and the error_code and error_desc fields in case of an error.

Errors:

 102 - unknown client
   103 - overlimit campaigns

Editing ad campaigns

To edit ad campaigns, use the ads.campaigns.update
method The maximum number of campaigns edited with a single query is 50.
Version log: 1.0.1 - added status parameter

Parameters	Value	Additional attributes
data </td>	is a serialized JSON array of objects describing changes in campaigns. Object descriptions client_mod_specification see below.	required parameter, string
client_specification
campaign_id	id of the edited campaign	required parameter, positive number
name	campaign name	optional parameter, a string between 3 and 60 characters
link_url	link to the advertised object in the format http: //yoursite.com	optional parameter, string
real_url	link to the real domain of the advertised object in the format: http: //yoursite.cоm	optional parameter, string
sex	Gender: 3 - any; 2 - male; 1 - female	optional parameter, int (numeric value)
age	age: /data.ages	optional parameter, int (numeric value)
countryTarget	Countries id: /ads.targeting.countries.get	required parameter array [country_id => [ bid => 0.1, leadCost => 0.2 ] ]
regionTarget	ID regions: /ads.targeting.regions.get	required parameter, a sequence of numbers separated by a comma
cityTarget	ID cities: /ads.targeting.cities.get	required parameter, a sequence of numbers separated by a comma
categories	category IDs: /data.categories.get?ad_format =% category_id: {region_id: cost}	optional parameter
tags	keyword targeting	optional parameter, comma separated keyword sequence
day_limit	daily limit in rubles. for all types except clickunder	optional parameter, positive number
adult_content	presence of adult content in the advertising campaign: 0 - No; 1 - Yes	optional parameter, int (numeric value), default 0
adult_site	display campaign ads on adult content sites: 0 - No; 1 - Yes	optional parameter, int (numeric value), default 0
time_show	Time Targeting: & nbsp; & nbsp; * - display in any hours and days of the week & nbsp; & nbsp; {} is an array, where the key is the name of the day of the week ["Sn", "Mn", "Tu", "Wd", "Th", "Fr", "Sa"]: & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; {} - ‘mn’: ‘*’ - all watches are weekly & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; & nbsp; {} - ‘mn’: [0, .., 23] - hours, separated by commas	optional parameter, * default
platforms	platform targeting: /data.platforms	comma separated numbers
browsers	browser targeting: /data.browsers	comma separated numbers
black_list	black list of sites where ads will not be shown	comma separated site ID number sequence
white_list	white list of sites where ads will not be shown	comma separated site ID number sequence
black_list_ip	ip lock	sequence of ip addresses separated by a comma or an array
status	start /pause campaign: 0 - suspended; 1 - running	optional parameter, int (numeric value), default 1
deviceTarget	ID devices: /ads.targeting.devices.get	sequence of numbers separated by a comma
langTarget	ID browser languages: /ads.targeting.langs.get	sequence of numbers separated by a comma

Result:
Returns an array of responses to each request in the data array. The corresponding object in the output array contains the id of the client being changed and, in case of an error, the error_code and error_desc fields.

Errors:

 100 - unknown campaign
    102 - unknown client

List of campaign advertising campaign

To get a list of campaign advertising campaigns use the method ads.campaigns.get

Parameters	Value	Additional attributes
client_id	Client ID from which ad campaigns are requested	int (numeric value)
include_archive	A flag that specifies whether to display archived ads: 0 - show only active campaigns; 1 - show all campaigns	Flag, can be 1 or 0
campaign_ids	Filter for displayed ad campaigns. Serialized JSON array containing campaign id. Only campaigns that are present in the campaign_ids and are campaigns of the specified advertising cabinet will be displayed. If the parameter is null, then all campaigns will be displayed.	String
with_bwlist	Black and white list transfer flag	any value (for example 1)
with_tags	Keyword Transfer Flag	any value (for example 1)
limit	limit on the number of campaigns returned. Used only if the campaign_ids parameter is null	int (numeric value)
offset	offset. Used in the same cases as the limit parameter	int (numeric value)

Result:
Returns an array of campaign objects, each of which contains the following fields:


response: {
       count:% total%
       items: [{
id - campaign identifier
name - campaign name
status - campaign status (0 - campaign stopped, 1 - campaign started, 2 - campaign deleted)
day_limit - campaign daily limit in rubles (0 - no limit is set)
all_limit - total campaign limit in rubles (0 - no limit is set)
ad_format - ad format
cost_type - payment type
link_url - link to the advertised object
sex
age - age
regions - region identifiers
categories - category identifiers.
adult_content - the presence of adult content
adult_site - display campaign ads on adult content sites
           tags - keywords
           bw_list - black and white list
      }, ..]
}

Errors:

 102 - unknown client

Archiving an advertising campaign

To archive an existing advertising campaign, use the ads.campaigns.delete
method Ten (10) campaigns can be archived with a single request.

Parameters

Value

Additional attributes

ids

Campaign id list separated by comma or array with id campaigns.

For example:

“id1, id2, ..., idn“ or [id1, id2, ..., idn]

required parameter, string

Result:
Returns an array of responses to each request. Each answer is either 0, which means successful deletion, or an error array.

Errors:

 100 - unknown campaign
   101 - campaign already archive
   102 - unknown client

Receiving codes for CPA campaigns

Use the ads.campaigns.cpa.mode.get
method to get the codes for the CPA campaigns

Parameters	Value	Additional attributes
campaign_id	campaign id	int (numeric value), required parameter

Result:
Returns an object with data.


{
response: {
url:% url%
                  }
}

Getting a list of categories for a given filter

To return the list of categories for a given filter, use the ads.campaigns.categories.get
method

Parameters	Value	Additional attributes
ad_format	ad format: ads.campaigns.formats.get	required parameter, int (numeric value)
category_id	category id. limits displaying only by category id	optional parameter, int (numeric value)