Send an API request
Stay organized with collections
Save and categorize content based on your preferences.
After you complete the prerequisites
, generate the OAuth 2.0
credentials
, and configure your client
, you can use
the following code samples to create and retrieve a Bid Manager API reporting
query.
For a full list of Bid Manager API methods, see the reference
documentation
.
Create a query
Here's an example of how to create a Display & Video 360 reporting
query
:
Java
// Display name of the query to create.
String
displayName
=
display
-
name
;
// Advertiser ID and campaign ID by which to filter report data.
String
advertiserId
=
advertiser
-
id
;
String
campaignId
=
campaign
-
id
;
// Create the query structure.
Query
query
=
new
Query
();
// Build and set the metadata object.
QueryMetadata
metadata
=
new
QueryMetadata
();
metadata
.
setTitle
(
displayName
);
metadata
.
setDataRange
(
new
DataRange
().
setRange
(
"LAST_7_DAYS"
));
metadata
.
setFormat
(
"CSV"
);
query
.
setMetadata
(
metadata
);
// Build the parameters object.
Parameters
parameters
=
new
Parameters
();
parameters
.
setType
(
"STANDARD"
);
// Build and assign list of standard reporting dimensions to parameters object.
ArrayList<String
>
dimensions
=
new
ArrayList<String
>
();
dimensions
.
add
(
"FILTER_ADVERTISER_NAME"
);
dimensions
.
add
(
"FILTER_ADVERTISER"
);
dimensions
.
add
(
"FILTER_ADVERTISER_CURRENCY"
);
dimensions
.
add
(
"FILTER_INSERTION_ORDER_NAME"
);
dimensions
.
add
(
"FILTER_INSERTION_ORDER"
);
dimensions
.
add
(
"FILTER_LINE_ITEM_NAME"
);
dimensions
.
add
(
"FILTER_LINE_ITEM"
);
parameters
.
setGroupBys
(
dimensions
);
// Build a list of filters.
ArrayList<FilterPair
>
filters
=
new
ArrayList<FilterPair
>
();
filters
.
add
(
new
FilterPair
().
setType
(
"FILTER_ADVERTISER"
).
setValue
(
advertiserId
));
filters
.
add
(
new
FilterPair
().
setType
(
"FILTER_MEDIA_PLAN"
).
setValue
(
campaignId
));
// Set filters in parameters object.
parameters
.
setFilters
(
filters
);
// Build and assign list of standard reporting metrics to parameters object.
ArrayList<String
>
metrics
=
new
ArrayList<String
>
();
metrics
.
add
(
"METRIC_IMPRESSIONS"
);
metrics
.
add
(
"METRIC_BILLABLE_IMPRESSIONS"
);
metrics
.
add
(
"METRIC_CLICKS"
);
metrics
.
add
(
"METRIC_CTR"
);
metrics
.
add
(
"METRIC_TOTAL_CONVERSIONS"
);
metrics
.
add
(
"METRIC_LAST_CLICKS"
);
metrics
.
add
(
"METRIC_LAST_IMPRESSIONS"
);
metrics
.
add
(
"METRIC_REVENUE_ADVERTISER"
);
metrics
.
add
(
"METRIC_MEDIA_COST_ADVERTISER"
);
parameters
.
setMetrics
(
metrics
);
// Set parameters object in query.
query
.
setParams
(
parameters
);
// Build and set the schedule object.
QuerySchedule
schedule
=
new
QuerySchedule
();
schedule
.
setFrequency
(
"ONE_TIME"
);
query
.
setSchedule
(
schedule
);
// Create the query.
Query
queryResponse
=
service
.
queries
().
create
(
query
).
execute
();
// Log query creation.
System
.
out
.
printf
(
"Query %s was created.%n"
,
queryResponse
.
getQueryId
());
Python
# Display name of the query to create.
display_name
=
display
-
name
# Advertiser ID and campaign ID by which to filter report data.
advertiser_id
=
advertiser
-
id
campaign_id
=
campaign
-
id
# Build query object with basic dimension and metrics values.
query_obj
=
{
"metadata"
:
{
"title"
:
display_name
,
"dataRange"
:
{
"range"
:
"LAST_7_DAYS"
},
"format"
:
"CSV"
,
},
"params"
:
{
"type"
:
"STANDARD"
,
"groupBys"
:
[
"FILTER_ADVERTISER_NAME"
,
"FILTER_ADVERTISER"
,
"FILTER_ADVERTISER_CURRENCY"
,
"FILTER_INSERTION_ORDER_NAME"
,
"FILTER_INSERTION_ORDER"
,
"FILTER_LINE_ITEM_NAME"
,
"FILTER_LINE_ITEM"
,
],
"filters"
:
[
{
"type"
:
"FILTER_ADVERTISER"
,
"value"
:
advertiser_id
},
{
"type"
:
"FILTER_MEDIA_PLAN"
,
"value"
:
campaign_id
}
],
"metrics"
:
[
"METRIC_IMPRESSIONS"
,
"METRIC_BILLABLE_IMPRESSIONS"
,
"METRIC_CLICKS"
,
"METRIC_CTR"
,
"METRIC_TOTAL_CONVERSIONS"
,
"METRIC_LAST_CLICKS"
,
"METRIC_LAST_IMPRESSIONS"
,
"METRIC_REVENUE_ADVERTISER"
,
"METRIC_MEDIA_COST_ADVERTISER"
,
],
},
"schedule"
:
{
"frequency"
:
"ONE_TIME"
}
}
# Create query object.
query_response
=
service
.
queries
()
.
create
(
body
=
query_obj
)
.
execute
()
# Print new query ID.
print
(
f
'Query
{
query_response
[
"queryId"
]
}
was created.'
)
PHP
// Display name of the query to create.
$displayName = display-name
;
// Advertiser ID and campaign ID by which to filter data.
$advertiserId = advertiser-id
;
$campaignId = campaign-id
;
// Create the query structure.
$query = new Google_Service_DoubleClickBidManager_Query();
// Build and set the metadata object.
$metadata = new Google_Service_DoubleClickBidManager_QueryMetadata();
$metadata->setTitle($displayName);
$metadata->setFormat("CSV");
$dataRange = new Google_Service_DoubleClickBidManager_DataRange();
$dataRange->setRange("LAST_7_DAYS");
$metadata->setDataRange($dataRange);
$query->setMetadata($metadata);
// Build the parameters object.
$parameters = new Google_Service_DoubleClickBidManager_Parameters();
$parameters->setType("STANDARD");
// Build and assign list of standard reporting dimensions.
$parameters->setGroupBys(
array(
"FILTER_ADVERTISER_NAME",
"FILTER_ADVERTISER",
"FILTER_ADVERTISER_CURRENCY",
"FILTER_INSERTION_ORDER_NAME",
"FILTER_INSERTION_ORDER",
"FILTER_LINE_ITEM_NAME",
"FILTER_LINE_ITEM"
)
);
// Build and assign a list of filters.
$filters = array();
$advertiserFilterPair = new Google_Service_DoubleClickBidManager_FilterPair();
$advertiserFilterPair->setType("FILTER_ADVERTISER");
$advertiserFilterPair->setValue($advertiserId);
array_push($filters, $advertiserFilterPair);
$campaignFilterPair = new Google_Service_DoubleClickBidManager_FilterPair();
$campaignFilterPair->setType("FILTER_MEDIA_PLAN");
$campaignFilterPair->setValue($campaignId);
array_push($filters, $campaignFilterPair);
$parameters->setFilters($filters);
// Build and assign list of standard reporting metrics.
$parameters->setMetrics(
array(
"METRIC_IMPRESSIONS",
"METRIC_BILLABLE_IMPRESSIONS",
"METRIC_CLICKS",
"METRIC_CTR",
"METRIC_TOTAL_CONVERSIONS",
"METRIC_LAST_CLICKS",
"METRIC_LAST_IMPRESSIONS",
"METRIC_REVENUE_ADVERTISER",
"METRIC_MEDIA_COST_ADVERTISER"
)
);
// Set parameters object in query.
$query->setParams($parameters);
// Build and set the schedule object.
$schedule = new Google_Service_DoubleClickBidManager_QuerySchedule();
$schedule->setFrequency("ONE_TIME");
$query->setSchedule($schedule);
// Call the API, creating the query.
$queryResult = $this->service->queries->create($query);
printf('Query %s was created.
', $queryResult['queryId']);
Retrieve a query
Here's an example of how to retrieve a Display & Video 360 reporting
query
:
Java
// ID of query to retrieve.
Long
queryId
=
query
-
id
;
// Retrieve Display & Video 360 query.
Query
queryResponse
=
service
.
queries
().
get
(
queryId
).
execute
();
// Print display name of query.
System
.
out
.
printf
(
"Query ID %s was retrieved with display name %s.%n"
,
queryResponse
.
getQueryId
(),
queryResponse
.
getMetadata
().
getTitle
()
);
Python
# ID of query to retrieve.
query_id
=
query
-
id
# Retrieve Display & Video 360 query
query
=
service
.
queries
()
.
get
(
queryId
=
query_id
)
.
execute
()
# Print display name of query.
print
(
f
'Query ID
{
query_id
}
retrieved with display name'
f
'
{
query
[
"metadata"
][
"title"
]
}
.'
)
PHP
// ID of a query to retrieve.
$queryId = query-id
;
// Retrieve Display & Video 360 query.
$queryResponse = $this->service->queries->get($queryId);
printf(
'Query ID %s was retrieved with display name %s.
',
$queryId,
$queryResponse->getMetadata()->getTitle()
);
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License
, and code samples are licensed under the Apache 2.0 License
. For details, see the Google Developers Site Policies
. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-28 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[[["\u003cp\u003eThis page provides code samples in Java, Python, and PHP to demonstrate how to create and retrieve Display & Video 360 reporting queries using the Bid Manager API.\u003c/p\u003e\n"],["\u003cp\u003eBefore running the samples, you need to complete prerequisites, generate OAuth 2.0 credentials, and configure your client as instructed in the linked guides.\u003c/p\u003e\n"],["\u003cp\u003eThe "Create a query" section shows how to define query parameters such as data range, filters, dimensions, and metrics to retrieve specific report data.\u003c/p\u003e\n"],["\u003cp\u003eThe "Retrieve a query" section provides code snippets for fetching an existing query based on its ID and accessing its metadata, such as the display name.\u003c/p\u003e\n"],["\u003cp\u003eFor a comprehensive list of available Bid Manager API methods and further details, refer to the provided reference documentation link.\u003c/p\u003e\n"]]],["After prerequisite steps, the provided code samples demonstrate how to interact with the Bid Manager API. They show how to create a reporting query by defining its metadata (title, data range, format), parameters (type, dimensions, filters, metrics), and schedule (frequency). The examples also retrieve a query by its ID, obtaining and displaying its details, including the display name. These actions are illustrated in Java, Python, and PHP.\n"],null,["# Send an API request\n\nAfter you [complete the prerequisites](/bid-manager/guides/get-started/overview#prerequisites), [generate the OAuth 2.0\ncredentials](/bid-manager/guides/get-started/generate-credentials), and [configure your client](/bid-manager/guides/get-started/install-configure#configure_your_client), you can use\nthe following code samples to create and retrieve a Bid Manager API reporting\nquery.\n\nFor a full list of Bid Manager API methods, see the [reference\ndocumentation](/bid-manager/reference/rest).\n\nCreate a query\n--------------\n\nHere's an example of how to [create a Display \\& Video 360 reporting\nquery](/bid-manager/reference/rest/current/queries/create): \n\n### Java\n\n```java\n// Display name of the query to create.\nString displayName = display-name;\n\n// Advertiser ID and campaign ID by which to filter report data.\nString advertiserId = advertiser-id;\nString campaignId = campaign-id;\n\n// Create the query structure.\nQuery query = new Query();\n\n// Build and set the metadata object.\nQueryMetadata metadata = new QueryMetadata();\nmetadata.setTitle(displayName);\nmetadata.setDataRange(new DataRange().setRange(\"LAST_7_DAYS\"));\nmetadata.setFormat(\"CSV\");\nquery.setMetadata(metadata);\n\n// Build the parameters object.\nParameters parameters = new Parameters();\nparameters.setType(\"STANDARD\");\n\n// Build and assign list of standard reporting dimensions to parameters object.\nArrayList\u003cString\u003e dimensions = new ArrayList\u003cString\u003e();\ndimensions.add(\"FILTER_ADVERTISER_NAME\");\ndimensions.add(\"FILTER_ADVERTISER\");\ndimensions.add(\"FILTER_ADVERTISER_CURRENCY\");\ndimensions.add(\"FILTER_INSERTION_ORDER_NAME\");\ndimensions.add(\"FILTER_INSERTION_ORDER\");\ndimensions.add(\"FILTER_LINE_ITEM_NAME\");\ndimensions.add(\"FILTER_LINE_ITEM\");\nparameters.setGroupBys(dimensions);\n\n// Build a list of filters.\nArrayList\u003cFilterPair\u003e filters = new ArrayList\u003cFilterPair\u003e();\nfilters.add(new FilterPair().setType(\"FILTER_ADVERTISER\").setValue(advertiserId));\nfilters.add(new FilterPair().setType(\"FILTER_MEDIA_PLAN\").setValue(campaignId));\n\n// Set filters in parameters object.\nparameters.setFilters(filters);\n\n// Build and assign list of standard reporting metrics to parameters object.\nArrayList\u003cString\u003e metrics = new ArrayList\u003cString\u003e();\nmetrics.add(\"METRIC_IMPRESSIONS\");\nmetrics.add(\"METRIC_BILLABLE_IMPRESSIONS\");\nmetrics.add(\"METRIC_CLICKS\");\nmetrics.add(\"METRIC_CTR\");\nmetrics.add(\"METRIC_TOTAL_CONVERSIONS\");\nmetrics.add(\"METRIC_LAST_CLICKS\");\nmetrics.add(\"METRIC_LAST_IMPRESSIONS\");\nmetrics.add(\"METRIC_REVENUE_ADVERTISER\");\nmetrics.add(\"METRIC_MEDIA_COST_ADVERTISER\");\nparameters.setMetrics(metrics);\n\n// Set parameters object in query.\nquery.setParams(parameters);\n\n// Build and set the schedule object.\nQuerySchedule schedule = new QuerySchedule();\nschedule.setFrequency(\"ONE_TIME\");\nquery.setSchedule(schedule);\n\n// Create the query.\nQuery queryResponse = service.queries().create(query).execute();\n\n// Log query creation.\nSystem.out.printf(\"Query %s was created.%n\", queryResponse.getQueryId());\n```\n\n### Python\n\n```python\n# Display name of the query to create.\ndisplay_name = display-name\n\n# Advertiser ID and campaign ID by which to filter report data.\nadvertiser_id = advertiser-id\ncampaign_id = campaign-id\n\n# Build query object with basic dimension and metrics values.\nquery_obj = {\n \"metadata\": {\n \"title\": display_name,\n \"dataRange\": {\"range\": \"LAST_7_DAYS\"},\n \"format\": \"CSV\",\n },\n \"params\": {\n \"type\": \"STANDARD\",\n \"groupBys\": [\n \"FILTER_ADVERTISER_NAME\",\n \"FILTER_ADVERTISER\",\n \"FILTER_ADVERTISER_CURRENCY\",\n \"FILTER_INSERTION_ORDER_NAME\",\n \"FILTER_INSERTION_ORDER\",\n \"FILTER_LINE_ITEM_NAME\",\n \"FILTER_LINE_ITEM\",\n ],\n \"filters\": [\n {\"type\": \"FILTER_ADVERTISER\", \"value\": advertiser_id},\n {\"type\": \"FILTER_MEDIA_PLAN\", \"value\": campaign_id}\n ],\n \"metrics\": [\n \"METRIC_IMPRESSIONS\",\n \"METRIC_BILLABLE_IMPRESSIONS\",\n \"METRIC_CLICKS\",\n \"METRIC_CTR\",\n \"METRIC_TOTAL_CONVERSIONS\",\n \"METRIC_LAST_CLICKS\",\n \"METRIC_LAST_IMPRESSIONS\",\n \"METRIC_REVENUE_ADVERTISER\",\n \"METRIC_MEDIA_COST_ADVERTISER\",\n ],\n },\n \"schedule\": {\"frequency\": \"ONE_TIME\"}\n}\n\n# Create query object.\nquery_response = service.queries().create(body=query_obj).execute()\n\n# Print new query ID.\nprint(f'Query {query_response[\"queryId\"]} was created.')\n```\n\n### PHP\n\n```php\n// Display name of the query to create.\n$displayName = \u003cvar translate=\"no\"\u003edisplay-name\u003c/var\u003e;\n\n// Advertiser ID and campaign ID by which to filter data.\n$advertiserId = \u003cvar translate=\"no\"\u003eadvertiser-id\u003c/var\u003e;\n$campaignId = \u003cvar translate=\"no\"\u003ecampaign-id\u003c/var\u003e;\n\n// Create the query structure.\n$query = new Google_Service_DoubleClickBidManager_Query();\n\n// Build and set the metadata object.\n$metadata = new Google_Service_DoubleClickBidManager_QueryMetadata();\n$metadata-\u003esetTitle($displayName);\n$metadata-\u003esetFormat(\"CSV\");\n\n$dataRange = new Google_Service_DoubleClickBidManager_DataRange();\n$dataRange-\u003esetRange(\"LAST_7_DAYS\");\n$metadata-\u003esetDataRange($dataRange);\n\n$query-\u003esetMetadata($metadata);\n\n// Build the parameters object.\n$parameters = new Google_Service_DoubleClickBidManager_Parameters();\n$parameters-\u003esetType(\"STANDARD\");\n\n// Build and assign list of standard reporting dimensions.\n$parameters-\u003esetGroupBys(\n array(\n \"FILTER_ADVERTISER_NAME\",\n \"FILTER_ADVERTISER\",\n \"FILTER_ADVERTISER_CURRENCY\",\n \"FILTER_INSERTION_ORDER_NAME\",\n \"FILTER_INSERTION_ORDER\",\n \"FILTER_LINE_ITEM_NAME\",\n \"FILTER_LINE_ITEM\"\n )\n);\n\n// Build and assign a list of filters.\n$filters = array();\n$advertiserFilterPair = new Google_Service_DoubleClickBidManager_FilterPair();\n$advertiserFilterPair-\u003esetType(\"FILTER_ADVERTISER\");\n$advertiserFilterPair-\u003esetValue($advertiserId);\narray_push($filters, $advertiserFilterPair);\n\n$campaignFilterPair = new Google_Service_DoubleClickBidManager_FilterPair();\n$campaignFilterPair-\u003esetType(\"FILTER_MEDIA_PLAN\");\n$campaignFilterPair-\u003esetValue($campaignId);\narray_push($filters, $campaignFilterPair);\n\n$parameters-\u003esetFilters($filters);\n\n// Build and assign list of standard reporting metrics.\n$parameters-\u003esetMetrics(\n array(\n \"METRIC_IMPRESSIONS\",\n \"METRIC_BILLABLE_IMPRESSIONS\",\n \"METRIC_CLICKS\",\n \"METRIC_CTR\",\n \"METRIC_TOTAL_CONVERSIONS\",\n \"METRIC_LAST_CLICKS\",\n \"METRIC_LAST_IMPRESSIONS\",\n \"METRIC_REVENUE_ADVERTISER\",\n \"METRIC_MEDIA_COST_ADVERTISER\"\n )\n);\n\n// Set parameters object in query.\n$query-\u003esetParams($parameters);\n\n// Build and set the schedule object.\n$schedule = new Google_Service_DoubleClickBidManager_QuerySchedule();\n$schedule-\u003esetFrequency(\"ONE_TIME\");\n$query-\u003esetSchedule($schedule);\n\n// Call the API, creating the query.\n$queryResult = $this-\u003eservice-\u003equeries-\u003ecreate($query);\n\nprintf('Query %s was created.\n', $queryResult['queryId']);\n```\n\nRetrieve a query\n----------------\n\nHere's an example of how to [retrieve a Display \\& Video 360 reporting\nquery](/bid-manager/reference/rest/current/queries/get): \n\n### Java\n\n```java\n// ID of query to retrieve.\nLong queryId = query-id;\n\n// Retrieve Display & Video 360 query.\nQuery queryResponse = service.queries().get(queryId).execute();\n\n// Print display name of query.\nSystem.out.printf(\n \"Query ID %s was retrieved with display name %s.%n\",\n queryResponse.getQueryId(),\n queryResponse.getMetadata().getTitle()\n);\n```\n\n### Python\n\n```python\n# ID of query to retrieve.\nquery_id = query-id\n\n# Retrieve Display & Video 360 query\nquery = service.queries().get(queryId=query_id).execute()\n\n# Print display name of query.\nprint(\n f'Query ID {query_id} retrieved with display name'\n f' {query[\"metadata\"][\"title\"]}.'\n)\n```\n\n### PHP\n\n```php\n// ID of a query to retrieve.\n$queryId = \u003cvar translate=\"no\"\u003equery-id\u003c/var\u003e;\n\n// Retrieve Display & Video 360 query.\n$queryResponse = $this-\u003eservice-\u003equeries-\u003eget($queryId);\n\nprintf(\n 'Query ID %s was retrieved with display name %s.\n',\n $queryId,\n $queryResponse-\u003egetMetadata()-\u003egetTitle()\n);\n```"]]
