API/en — различия между версиями

Текущая версия на 14:47, 11 февраля 2019

Другие языки:

Содержание

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

API authorization

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.analytic.campaign.get

Parameters	Values	Optional attributes
campaign_id	campaign's id	int (numeric value), required parameter
region_id	region's id: data.geo.regions.get	int (numeric value), required parameter
period	The way data is grouped by date: day — daily statistics; month - monthly statistics Temporary restrictions are set by parameters date_from and date_to	required parameter, string
date_from	The starting date of the statistics to display. Different date format is 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 format is used for different parameter period values: day: YYYY-MM-DD, example: 2011-09-27; month: YYYY-MM, example: 2011-09	required parameter, string

Result:
Returns an object with data


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

Statistics on sites in the advertiser's account

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

Parameters	Value	Additional attributes
date_from	Start date of the statistics output.	string, format YYYY-MM-DD (example: 2017-05-15), filter parameter
date_to	The end date of the statistics output.	string, format YYYY-MM-DD (example: 2017-05-15), filter parameter
campaign_id	campaign id	required parameter, int (numeric value), filter parameter
signature	Signature (generated using a time token, see above)	required parameter, string
app_id	user id	required parameter, int (numeric value)
macros	site id	int (numeric value), write parameter, filter option
leads	Leads	int (numeric value), write parameter, filter option
views	Views	int (numeric value), write parameter, filter option
clicks	Clicks	int (numeric value), write parameter, filter option
conversions	Confirmed Conversions	int (numeric value), write parameter, filter option
rejections	Failed Conversions	int (numeric value), write parameter, filter option
ctr	CTR	int (numeric value), write parameter, filter option
cpm	CPM	int (numeric value), write parameter, filter option
cpc	CPC	int (numeric value), write parameter, filter option
prelandvisit	Pre-landing Visits	int (numeric value), write parameter, filter option
prelanduseful	Pre-landing Useful visits	int (numeric value), write parameter, filter option
prelandscroll	Pre-landing Scroll	int (numeric value), write parameter, filter option

Result:
Returns an object with data, example:


{
  "response": {
    "count": 1,
    "items": [
      {
        "macros": "12345678901234",
        "block": "1234",
        "domain": "123456789",
        "leads": "0",
        "views": "123",
        "clicks": "0",
        "conversions": "0",
        "rejections": "0",
        "ctr": "0.0000",
        "cpm": "0.00",
        "cpc": null,
        "moneyOut": "0.000000",
        "moneyIn": null,
        "prelandvisit": "0",
        "prelanduseful": "0",
        "prelandscroll": "0",
        "landvisit": "0",
        "landuseful": "0",
        "landscroll": "0",
        "multiplier": null,
        "blackList": "0"
      }
    ],
    "request": {
      "campaignId": 123456,
      "limit": 10,
      "offset": 0
    }
  }
}

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.campaigns.statblock method (PUT request)

Parameters (all are required):

app_id - user id, numeric value (int)
signature - signature, string (string)
campaign_id - campaign id, numeric value (int)
block - a numeric value (int)
domain - numeric value (int)
multiplier - new multiplier value, numeric value (float)
multiplierOld - old multiplier value, numeric value (float)
macros - pad 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.analytic.materials.get method

Parameters	Value	Additional attributes
campaign_id	campaign 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 format is 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 format is 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: {
teaser_id
date
shows
clicks
ctr
cpm
money
                       }
                  }
}

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 format is 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 format is 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 The number of campaigns created with a single request is 50.

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
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
regions	Regions, from 1 to 10 (1 - Russia, 2 - Ukraine, etc.)	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 =%	array [category_id => cost]
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

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)
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

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 advertising campaign, use the ads.campaigns.delete
method The maximum number of clients edited with a single query is 10.

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.foarmats.get	required parameter, int (numeric value)
category_id	category id. limits displaying only by category id	optional parameter, int (numeric value)