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.

Alert

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:

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

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.

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"
   }
}

Was the article helpful?

UpdateClientInfo (Live)

GetChanges (Live)