GetChanges

Checks for changes in campaigns, ads, and clients' personal data, as well as in the region and time zone directories, and in the Yandex Catalog.

Attention.

Disabled method. Use version 5 of the API.

For information about the compatibility of methods between versions 4 and 5, see the Migration guide.

The Get Changes (Live) version also exists for this method.

The method states whether or not changes have been made since the date specified, without providing any details on what changed. We recommend using the method in the following way:

  1. At the first launch of the app, call the method without input parameters in order to synchronize the current time.

    The method returns the Timestamp parameter, which is the current UTC time on the server.

  2. For each method call after this, specify the usernames, campaigns, and ads to check changes for, along with the value of the Timestamp parameter received in the previous method call. This guarantees that there will be no gaps between the intervals for checking for changes, regardless of possible delays or discrepancies between the time on the server and the time in the app.
  3. If the response indicates changes, use the corresponding methods to get current data:
Note.

In some cases, the parameters of campaigns, ads, and other data are the same as previously, but the GetChanges method indicates changes. This is because the GetChanges method checks hidden parameters that are not accessible via the API.

Input data

The input data structure in JSON is shown below. The parameters CampaignIDS, BannerIDS and Logins are mutually exclusive; only one of them can be included in the request.

{
   "method": "GetChanges",
   "param": {
      /* GetChangesRequest */
      "CampaignIDS": [
         (int)
         ...
      ],
      "BannerIDS": [
         (long)
         ...
      ],
      "Logins": [
         (string)
         ...
      ],
      "Timestamp": (string)
   }
}

Parameters are described below.

Parameter Description Required
GetChangesRequest object
CampaignIDS

Array containing campaign identifiers (no more than 100).

No
BannerIDS

Array containing ad identifiers (no more than 100). The ads can belong to different campaigns.

No
Logins

Array of client (agency) usernames.

No
Timestamp The exact time to start from to check for changes. Specified in the format YYYY-MM-DDThh:mm:ssZ (conforming to ISO 8601), for example 2014-05-24T23:59:59Z. If the method is called without the Timestamp parameter, the other parameters are ignored and it returns only the current time on the server. No
Parameter Description Required
GetChangesRequest object
CampaignIDS

Array containing campaign identifiers (no more than 100).

No
BannerIDS

Array containing ad identifiers (no more than 100). The ads can belong to different campaigns.

No
Logins

Array of client (agency) usernames.

No
Timestamp The exact time to start from to check for changes. Specified in the format YYYY-MM-DDThh:mm:ssZ (conforming to ISO 8601), for example 2014-05-24T23:59:59Z. If the method is called without the Timestamp parameter, the other parameters are ignored and it returns only the current time on the server. No

Output data

The output data structure in JSON is shown below. The structure contains all possible data that can be included in the response. The data that is actually included depends on the input parameters and is described below.

{
   "data": {
      /* GetChangesResponse */
      "Campaigns": {
         /* GetChangesIntData */
         "Updated": [
            (int)
            ...
         ],
         "NotUpdated": [
            (int)
            ...
         ],
         "NotFound": [
            (int)
            ...
         ]
      },
      "Banners": {
         /* GetChangesLongData */
         "Updated": [
            (long)
            ...
         ],
         "NotUpdated": [
            (long)
            ...
         ],
         "NotFound": [
            (long)
            ...
         ]
      },
      "Logins": {
         /* GetChangesStringData */
         "Updated": [
            (string)
            ...
         ],
         "NotUpdated": [
            (string)
            ...
         ],
         "NotFound": [
            (string)
            ...
         ]
      },
      "CampaignsStatChange": [
         {  /* CampaignStatChangeItem */
            "CampaignID": (int),
            "BorderDate": (date)
         }
         ...
      ],
      "Timestamp": (string),
      "RubricsChanged": (string),
      "TimeZonesChanged": (string),
      "RegionsChanged": (string)
   }
}

Parameters are described below.

Parameter Description
GetChangesResponse object
Campaigns

Present in the response if the CampaignIDS array was included in the method call. Shows whether or not there are changes in the campaigns, or that the campaigns with the specified IDs were not found.

Changes to the campaigns are defined as changes to parameters that are returned by the GetCampaignsParams method, including significant changes in the campaign status.

Banners

Present in the response if a CampaignIDS array or BannerIDS array was included in the method call. For the former, it shows whether or not there are changes in ads that belong to the specified campaigns; for the latter, it shows the same for the specified ads, or that ads with these IDs were not found.

Changes to the ads are defined as changes to parameters that are returned by the GetBanners method, including significant changes in the ad status.

Logins

Present in the response if the Logins array was included in the method call. Shows whether or not there are changes in the clients' personal data.

CampaignsStatChange

Array of CampaignStatChangeItem objects. The objects contain the date when statistics were current (BorderDate) for campaigns that had statistics adjusted during the period being checked. If there are no such campaigns, the parameter is not included in output.

The campaigns being checked are specified explicitly in the CampaignIDS array, or are determined as belonging to clients whose usernames are listed in the Logins parameters.

Timestamp The exact time when the GetChanges method was executed. Output in the format YYYY-MM-DDThh:mm:ssZ, for example 2014-05-24T23:59:59Z. The timestamp is specified in the next GetChanges method call, to check for new changes since this time.
RubricsChanged Shows whether or not there are any changes in the Yandex Catalog — Yes/No.
TimeZonesChanged Shows whether or not there are any changes in the time zone directory — Yes/No.
RegionsChanged Shows whether or not there are any changes in the region directory — Yes/No.
GetChangesIntData object
NotUpdated Contains IDs of campaigns specified in the call that did not have any changes.
Updated

Contains IDs of campaigns specified in the call that had changes.

NotFound Contains IDs of campaigns specified in the call that were removed or did not exist.
GetChangesLongData object
NotUpdated Contains IDs of ads specified in the call that did not have any changes.
Updated

Contains IDs of ads specified in the call that had changes.

NotFound Contains IDs of ads specified in the call that were removed or did not exist.
GetChangesStringData object
NotUpdated Contains the usernames specified in the method call that do not have any changes in the clients' personal data.
Updated Contains the usernames specified in the method call that have changes in the clients' personal data.
NotFound Contains usernames specified in the method call that were deleted or did not exist.
CampaignStatChangeItem object
CampaignID The campaign ID.
BorderDate

Date when statistics were current. Output only for campaigns with statistics that were adjusted during the period being checked. Adjustments are usually made because of a declining click rate and an increasing campaign balance.

Statistics reports that were generated earlier may turn out to be inaccurate if they show data after BorderDate. We recommend re-creating such reports.

Parameter Description
GetChangesResponse object
Campaigns

Present in the response if the CampaignIDS array was included in the method call. Shows whether or not there are changes in the campaigns, or that the campaigns with the specified IDs were not found.

Changes to the campaigns are defined as changes to parameters that are returned by the GetCampaignsParams method, including significant changes in the campaign status.

Banners

Present in the response if a CampaignIDS array or BannerIDS array was included in the method call. For the former, it shows whether or not there are changes in ads that belong to the specified campaigns; for the latter, it shows the same for the specified ads, or that ads with these IDs were not found.

Changes to the ads are defined as changes to parameters that are returned by the GetBanners method, including significant changes in the ad status.

Logins

Present in the response if the Logins array was included in the method call. Shows whether or not there are changes in the clients' personal data.

CampaignsStatChange

Array of CampaignStatChangeItem objects. The objects contain the date when statistics were current (BorderDate) for campaigns that had statistics adjusted during the period being checked. If there are no such campaigns, the parameter is not included in output.

The campaigns being checked are specified explicitly in the CampaignIDS array, or are determined as belonging to clients whose usernames are listed in the Logins parameters.

Timestamp The exact time when the GetChanges method was executed. Output in the format YYYY-MM-DDThh:mm:ssZ, for example 2014-05-24T23:59:59Z. The timestamp is specified in the next GetChanges method call, to check for new changes since this time.
RubricsChanged Shows whether or not there are any changes in the Yandex Catalog — Yes/No.
TimeZonesChanged Shows whether or not there are any changes in the time zone directory — Yes/No.
RegionsChanged Shows whether or not there are any changes in the region directory — Yes/No.
GetChangesIntData object
NotUpdated Contains IDs of campaigns specified in the call that did not have any changes.
Updated

Contains IDs of campaigns specified in the call that had changes.

NotFound Contains IDs of campaigns specified in the call that were removed or did not exist.
GetChangesLongData object
NotUpdated Contains IDs of ads specified in the call that did not have any changes.
Updated

Contains IDs of ads specified in the call that had changes.

NotFound Contains IDs of ads specified in the call that were removed or did not exist.
GetChangesStringData object
NotUpdated Contains the usernames specified in the method call that do not have any changes in the clients' personal data.
Updated Contains the usernames specified in the method call that have changes in the clients' personal data.
NotFound Contains usernames specified in the method call that were deleted or did not exist.
CampaignStatChangeItem object
CampaignID The campaign ID.
BorderDate

Date when statistics were current. Output only for campaigns with statistics that were adjusted during the period being checked. Adjustments are usually made because of a declining click rate and an increasing campaign balance.

Statistics reports that were generated earlier may turn out to be inaccurate if they show data after BorderDate. We recommend re-creating such reports.

Examples of input data

Python

{
   'CampaignIDS': [1327944,1327967],
   'Timestamp': '2011-05-24T23:59:59Z'
}

PHP

array(
   'BannerIDS' => array(1974642, 20920155, 20155899, 64654),
   'Timestamp' => '2011-05-24T23:59:59Z'
)

Perl

{
   'Logins' => ['agrom', 'john_smith', 'john_smith_old'],
   'Timestamp' => '2011-05-24T23:59:59Z'
}

Examples of output data

The set of output data depends on the input parameters. In all cases, the method returns the current time on the server in the Timestamp parameter.

Call without parameters

Returns the current time on the server.

{
   "data": {
      "Timestamp": "2011-05-24T23:59:59Z"
   }
}

Call with the Timestamp parameter

Returns information about whether there are changes in Yandex Catalog, the region reference, or the time zone reference.

{
   "data": {
      "Timestamp": "2011-05-24T23:59:59Z",
      "RubricsChanged": "Yes",
      "TimeZonesChanged": "No",
      "RegionsChanged": "No"
   }
}

Call with the BannerIDS and Timestamp parameters

Returns information about whether there have been any changes to ads since the specified date.

{
   "data": {
      "Banners": {
         "Updated": [1974642, 20920155],
         "NotUpdated": [20155899],
         "NotFound": [64654]
      },
      "Timestamp": "2011-05-24T23:59:59Z",
      "RubricsChanged": "Yes",
      "TimeZonesChanged": "No",
      "RegionsChanged": "No"
   }
}

Call with the CampaignIDS and Timestamp parameters

Returns information about whether there have been any changes to campaigns or ads since the specified date, along with the dates when statistics were current.

{
   "data": {
      "Campaigns": {
         "Updated": [1327944]
      },
      "Banners": {
         "Updated": [123123,123123],
         "NotUpdated": [43532452],
      },
      "CampaignsStatChange": [
         {
            "CampaignID": 1327944,
            "BorderDate": "2011-03-17"
         }
      ],
      "Timestamp": "2011-05-24T23:59:59Z",
      "RubricsChanged": "Yes",
      "TimeZonesChanged": "No",
      "RegionsChanged": "No"
   }
}

Call with the Logins and Timestamp parameters

Returns information about whether any changes were made to clients' personal data, along with the date when statistics were current for campaigns that belong to these clients.

{
   "data": {
     "Logins": {
         "Updated": ["agrom"],
         "NotUpdated": ["john_smith"],
         "NotFound": ["john_smith_old"]
      },
     "CampaignsStatChange": [
         {
            "CampaignID": 1327944,
            "BorderDate": "2011-03-17"
         },
         {
            "CampaignID": 23667919,
            "BorderDate": "2011-05-17"
         }
      ],
      "Timestamp": "2011-05-24T23:59:59Z",
      "RubricsChanged": "No",
      "TimeZonesChanged": "No",
      "RegionsChanged": "No"
   }
}