Documentation

check

Informs you of changes in the client's campaigns, groups, and ads, starting from the specified date.

Request

Request structure in JSON format:

{
  "method": "check",
  "params": { 
    "CampaignIds
[no-highlight[

IDs of the campaigns to check for changes. From 1 to 3000 items in the array.

Required

Either CampaignIds, AdGroupIds, or AdIds

]no-highlight]
": [(long)], "AdGroupIds
[no-highlight[

IDs of the groups to check for changes. From 1 to 10,000 items in the array.

Required

Either CampaignIds, AdGroupIds, or AdIds

]no-highlight]
": [(long)], "AdIds
[no-highlight[

IDs of the ads to check for changes. From 1 to 50,000 items in the array.

Required

Either CampaignIds, AdGroupIds, or AdIds

]no-highlight]
": [(long)], "Timestamp
[no-highlight[

The exact time to start from to check for changes. Specified in the format YYYY-MM-DDThh:mm:ssZ (conforming to ISO 8601), such as 2015-05-24T23:59:59Z.

Required

Yes

]no-highlight]
": (string), /* required */ "FieldNames
[no-highlight[

Which types of changes to check for:

  • CampaignIds — Changes in campaign parameters (not including changes in child groups, ads, and keywords).
  • CampaignsStat — Corrected campaign statistics (usually related to filtering out false clicks).
  • AdGroupIds — Changes in ad groups and keywords (not including changes in ads).
  • AdIds — Changes to ads.

Changes are checked for all related objects. For example, if the request specifies the AdIds input parameter and the CampaignIds value in the FieldNames array, it checks for changes in campaigns that the specified ads belong to. For more information, see Examples below.

Required

Yes

]no-highlight]
": [( "CampaignIds" | "AdGroupIds" | "AdIds" | "CampaignsStat" )] /* required */ } }
Parameter Type Description Required
params structure (for JSON) / CheckRequest structure (for SOAP)
CampaignIds array of longIDs of the campaigns to check for changes. From 1 to 3000 items in the array.Either CampaignIds, AdGroupIds, or AdIds
AdGroupIds array of longIDs of the groups to check for changes. From 1 to 10,000 items in the array.
AdIds array of longIDs of the ads to check for changes. From 1 to 50,000 items in the array.
FieldNames array of FieldNamesEnum

Which types of changes to check for:

  • CampaignIds — Changes in campaign parameters (not including changes in child groups, ads, and keywords).
  • CampaignsStat — Corrected campaign statistics (usually related to filtering out false clicks).
  • AdGroupIds — Changes in ad groups and keywords (not including changes in ads).
  • AdIds — Changes to ads.

Changes are checked for all related objects. For example, if the request specifies the AdIds input parameter and the CampaignIds value in the FieldNames array, it checks for changes in campaigns that the specified ads belong to. For more information, see Examples below.

Yes
Timestamp stringThe exact time to start from to check for changes. Specified in the format YYYY-MM-DDThh:mm:ssZ (conforming to ISO 8601), such as 2015-05-24T23:59:59Z.Yes
Note. The parameters CampaignIds, AdGroupIds and AdIds are mutually exclusive. Only one of them can be included in the request.

Response

Response structure in JSON format:

{
  "result": { 
   "Modified
[no-highlight[

Objects specified in the request or associated with them that had changes.

]no-highlight]
": { /* CheckResponseModified */ "CampaignIds
[no-highlight[

IDs of campaigns that had changes in the parameters (changes in child objects and ads do not count).

]no-highlight]
": [(long), ... ], "AdGroupIds
[no-highlight[

IDs of groups that had changes (includes changes in keywords, but changes in ads do not count).

]no-highlight]
": [(long), ... ], "AdIds
[no-highlight[

IDs of ads that had changes.

]no-highlight]
": [(long), ... ], "CampaignsStat
[no-highlight[

Campaigns that had statistics corrected.

]no-highlight]
": [{ /* CampaignStatItem */ "CampaignId
[no-highlight[

The campaign ID.

]no-highlight]
": (long), /* required */ "BorderDate
[no-highlight[

Date when statistics were current. Output only for campaigns with statistics that were adjusted during the period being checked. Corrections to statistics are usually related to filtering out false clicks, and lead to a reduction in the number of clicks and an increase in the 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.

]no-highlight]
": (string) /* required */ }, ... ] }, "NotFound
[no-highlight[

Objects specified in the request that were not found.

]no-highlight]
": { /* CheckResponseIds */ "CampaignIds
[no-highlight[

IDs of campaigns.

]no-highlight]
": [(long), ... ], "AdGroupIds
[no-highlight[

Group IDs.

]no-highlight]
": [(long), ... ], "AdIds
[no-highlight[

IDs of ads.

]no-highlight]
": [(long), ... ] }, "Unprocessed
[no-highlight[

Objects specified in the request that were not processed. For these objects, you must make a separate request.

]no-highlight]
": { /* CheckResponseIds */ "CampaignIds
[no-highlight[

IDs of campaigns.

]no-highlight]
": [(long), ... ], "AdGroupIds
[no-highlight[

Group IDs.

]no-highlight]
": [(long), ... ], "AdIds
[no-highlight[

IDs of ads.

]no-highlight]
": [(long), ... ] }, "Timestamp
[no-highlight[

The exact time when the method was executed. Specified in the format YYYY-MM-DDThh:mm:ssZ (conforming to ISO 8601), such as 2015-05-24T23:59:59Z. The timestamp is specified in the next method call, to check for changes starting from this time.

]no-highlight]
": (string) } }
Parameter Type Description
result structure (for JSON) / CheckResponse structure (for SOAP)
Modified CheckResponseModified

Objects specified in the request or associated with them that had changes.

NotFound CheckResponseIds

Objects specified in the request that were not found.

Unprocessed CheckResponseIds

Objects specified in the request that were not processed. For these objects, you must make a separate request.

Timestamp stringThe exact time when the method was executed. Specified in the format YYYY-MM-DDThh:mm:ssZ (conforming to ISO 8601), such as 2015-05-24T23:59:59Z. The timestamp is specified in the next method call, to check for changes starting from this time.
CheckResponseModified structure
CampaignIds array of longIDs of campaigns that had changes in the parameters (changes in child objects and ads do not count).
AdGroupIds array of longIDs of groups that had changes (includes changes in keywords, but changes in ads do not count).
AdIds array of longIDs of ads that had changes.
CampaignsStat array of CampaignStatItemCampaigns that had statistics corrected.
CampaignStatItem structure
CampaignId longThe campaign ID.
BorderDate string

Date when statistics were current. Output only for campaigns with statistics that were adjusted during the period being checked. Corrections to statistics are usually related to filtering out false clicks, and lead to a reduction in the number of clicks and an increase in the 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.

CheckResponseIds structure
CampaignIds array of longIDs of campaigns.
AdGroupIds array of longGroup IDs.
AdIds array of longIDs of ads.

Examples

Checks for changes in groups and keywords for the specified campaigns
{
  "method": "check",
  "params": {
    "CampaignIds": [13765,13767],
    "FieldNames": ["AdGroupIds"],
    "Timestamp": "2015-02-02T10:08:22Z"
  }
}

Response:

{
  "result": {
    "Modified": {
      "AdGroupIds": [23543,23544,23874]
    }
    "Timestamp": "2015-02-02T12:23:11Z"
  }
}

Comments: changes were made in three groups (or keywords in these groups).

Checks for changes in the set campaigns and their child groups and ads
{
  "method": "check",
  "params": {
    "CampaignIds": [13765,13766,13767,13769],
    "FieldNames": ["CampaignIds","CampaignsStat","AdGroupIds","AdIds"],
    "Timestamp": "2015-02-02T10:08:22Z"
  }
}

Response:

{
  "result": {
    "Modified": {
      "CampaignIds": [13767,13769],
      "AdGroupIds": [23543,23544,23874],
      "AdIds": [33651,33921,34028,34106],
      "CampaignsStat": [
        {
          "CampaignId": 13767,
          "BorderDate": "2015-01-28"
        }
      ]
    },
    "NotFound": {
      "CampaignIds": [13765]
    },
    "Timestamp": "2015-02-02T12:23:11Z"
  }
}

Comments: changes were made in two campaigns, three child groups (or keywords in these groups), and four child ads. In one campaign, statistics were corrected. One campaign was not found.

Checks for changes in the set ads and their parent groups and campaigns
{
  "method": "check",
  "params": {
    "AdIds": [33651,33732,34028,34029],
    "FieldNames": ["CampaignIds","AdGroupIds","AdIds"],
    "Timestamp": "2015-02-02T10:08:22Z"
  }
}

Response:

{
  "result": {
    "Modified": {
      "CampaignIds": [13767],
      "AdGroupIds": [],
      "AdIds": [33651,34028]
    },
    "NotFound": {
      "AdIds": [33732]
    },
    "Timestamp": "2015-02-02T12:25:19Z"
  }
}

Comments: changes were made to two ads and one campaign, which contains one or more ads specified in the request. One ad was not found.

Checks for changes in the set group and ads in the group, as well as in the parent campaign
{
  "method": "check",
  "params": {
    "AdGroupIds": [23764],
    "FieldNames": ["CampaignIds","AdGroupIds","AdIds"],
    "Timestamp": "2015-02-02T10:08:22Z"
  }
}

Response:

{
  "result": {
    "Modified": {
      "CampaignIds": [],
      "AdGroupIds": [],
      "AdIds": [33651,34028]
    },
    "Timestamp": "2015-02-02T12:25:19Z"
  }
}

Comments: no changes were made in the group (or this group's keywords), or in the parent campaign. There were changes to two ads from the group.

Checks for changes in the set groups and ads in the groups, as well as in parent campaigns
{
  "method": "check",
  "params": {
    "AdGroupIds": [23543,23544,23874],
    "FieldNames": ["CampaignIds","AdGroupIds","AdIds"],
    "Timestamp": "2015-02-02T12:25:19Z"
  }
}

Response:

{
  "result": {
    "Modified": {
      "CampaignIds": [13767],
      "AdGroupIds": [23543],
      "AdIds": [33651,33732,34028,34029,33921,34028,34106]
    },
    "Unprocessed": {
      "AdGroupIds": [23544,23874]
    },
    "Timestamp": "2015-02-02T14:51:40Z"
  }
}

Comments: changes were made to one group (or keywords in this group), the campaign this group belongs to, and seven of the group's ads. Two groups were not processed: they might have also had changes, so a separate request is necessary.