Our client libraries provide high-level views and basic building blocks of
Google Ads API functionality, making it easier to develop apps quickly. We recommend
starting out with one if you're new to the API.
| Client library | Source | Distribution | Code examples |
|---|---|---|---|
| [Java](https://developers.google.com/google-ads/api/docs/client-libs/java) | [google-ads-java](https://github.com/googleads/google-ads-java/) | [Maven](https://github.com/googleads/google-ads-java/#maven-artifacts), [tar.gz](https://github.com/googleads/google-ads-java/releases) | [View on GitHub](https://github.com/googleads/google-ads-java/blob/HEAD/google-ads-examples/src/main/java/com/google/ads/googleads/examples) |
| [.NET](https://developers.google.com/google-ads/api/docs/client-libs/dotnet) | [google-ads-dotnet](https://github.com/googleads/google-ads-dotnet) | [nuget](https://www.nuget.org/packages/Google.Ads.GoogleAds), [tar.gz, zip](https://github.com/googleads/google-ads-dotnet/releases) | [View on GitHub](https://github.com/googleads/google-ads-dotnet/blob/main/Google.Ads.GoogleAds/examples) |
| [PHP](https://developers.google.com/google-ads/api/docs/client-libs/php) | [google-ads-php](https://github.com/googleads/google-ads-php) | [tar.gz](https://github.com/googleads/google-ads-php/releases) | [View on GitHub](https://github.com/googleads/google-ads-php/blob/HEAD/examples) |
| [Python](https://developers.google.com/google-ads/api/docs/client-libs/python) | [google-ads-python](https://github.com/googleads/google-ads-python) | [tar.gz, zip](https://github.com/googleads/google-ads-python/releases) | [View on GitHub](https://github.com/googleads/google-ads-python/tree/HEAD/examples) |
| [Ruby](https://developers.google.com/google-ads/api/docs/client-libs/ruby) | [google-ads-ruby](https://github.com/googleads/google-ads-ruby/) | [gem, tar.gz, zip](https://github.com/googleads/google-ads-ruby/releases) | [View on GitHub](https://github.com/googleads/google-ads-ruby/tree/HEAD/examples) |
| [Perl](https://developers.google.com/google-ads/api/docs/client-libs/perl) | [google-ads-perl](https://github.com/googleads/google-ads-perl/) | [tar.gz, zip](https://github.com/googleads/google-ads-perl/releases) | [View on GitHub](https://github.com/googleads/google-ads-perl/blob/HEAD/examples) |
## Community Libraries
We are aware of several libraries that are maintained by the open source
community. We maintain this list to help interested developers find them. We
don't test, contribute to, or maintain these libraries; use them at your own
risk. Any questions you may have should be directed to the owners of the
open source projects.
If you are aware of a library that we have missed, click **Send feedback**
at the top of the page and let us know.
- NodeJS: [https://www.npmjs.com/package/google-ads-api](https://www.npmjs.com/package/google-ads-api)
- Go: [https://github.com/shenzhencenter/google-ads-pb](https://github.com/shenzhencenter/google-ads-pb)
## Supported API versions
The table shows which client libraries work with which API versions.
The listed minimum client library version is sufficient for the major Google Ads API
release (such as v24). To see the required client library version for minor
releases, refer to the linked Changelog.
### Java
[Changelog](https://github.com/googleads/google-ads-java/blob/main/CHANGELOG.md)
|---|---|
| ##### Google Ads API | ##### Client library for Java |
| `v24` | Min: `43.0.0` Max: - |
| `v23` | Min: `42.0.0` Max: - |
| `v22` | Min: `41.0.0` Max: - |
| `v21` | Min: `39.0.0` Max: - |
### C#
[Changelog](https://github.com/googleads/google-ads-dotnet/blob/main/CHANGELOG.md)
|---|---|
| ##### Google Ads API | ##### Client library for .NET |
| `v24` | Min: `25.3.0` Max: - |
| `v23` | Min: `25.1.0` Max: - |
| `v22` | Min: `24.1.0` Max: - |
| `v21` | Min: `24.0.0` Max: - |
### PHP
[Changelog](https://github.com/googleads/google-ads-php/blob/main/CHANGELOG.md)
|---|---|
| ##### Google Ads API | ##### Client library for PHP |
| `v24` | Min: `33.3.0` Max: - |
| `v23` | Min: `32.2.0` Max: - |
| `v22` | Min: `31.0.0` Max: - |
| `v21` | Min: `28.0.0` Max: - |
### Python
[Changelog](https://github.com/googleads/google-ads-python/blob/main/ChangeLog)
|---|---|
| ##### Google Ads API | ##### Client library for Python |
| `v24` | Min: `30.1.0` Max: - |
| `v23` | Min: `29.2.0` Max: - |
| `v22` | Min: `28.1.0` Max: - |
| `v21` | Min: `28.0.0` Max: - |
### Ruby
[Changelog](https://github.com/googleads/google-ads-ruby/blob/main/CHANGELOG.md)
|---|---|
| ##### Google Ads API | ##### Client library for Ruby |
| `v24` | Min: `40.0.0` Max: - |
| `v23` | Min: `38.0.0` Max: - |
| `v22` | Min: `36.0.0` Max: - |
| `v21` | Min: `35.0.0` Max: - |
### Perl
[Changelog](https://github.com/googleads/google-ads-perl/blob/main/CHANGELOG.md)
|---|---|
| ##### Google Ads API | ##### Client library for Perl |
| `v24` | Min: `32.0.0` Max: - |
| `v23` | Min: `31.0.0` Max: - |
| `v22` | Min: `29.0.0` Max: - |
| `v21` | Min: `28.0.0` Max: - |
## Configuration
Each Ads API Client library provides different configuration settings and
loading methods that you can use to customize its behavior.
Here are the environment variables that are common to all client libraries and
that can be loaded to set configuration settings:
- **Client library**
- `GOOGLE_ADS_CONFIGURATION_FILE_PATH`: Path to the configuration file.
- **OAuth2**
- **Application Mode**
- `GOOGLE_ADS_CLIENT_ID` : Set this value to your OAuth2 client ID.
- `GOOGLE_ADS_CLIENT_SECRET` : Set this value to your OAuth2 client secret.
- `GOOGLE_ADS_REFRESH_TOKEN` : Set this value to a pre-generated OAuth2 refresh token if you want to reuse OAuth2 tokens. This setting is optional.
- **Service Account Mode**
- `GOOGLE_ADS_JSON_KEY_FILE_PATH` : Set this value to the OAuth2 JSON configuration file path.
- `GOOGLE_ADS_IMPERSONATED_EMAIL` : Set this value to the email address of the account you are impersonating.
- **Google Ads API**
- `GOOGLE_ADS_DEVELOPER_TOKEN` : Set this to your developer token.
- `GOOGLE_ADS_LOGIN_CUSTOMER_ID` : This is the customer ID of the authorized customer to use in the request, without hyphens (`-`).
- `GOOGLE_ADS_LINKED_CUSTOMER_ID` : This header is only required for methods that update the resources of an entity when permissioned through Linked Accounts in the Google Ads UI (`AccountLink` resource in the Google Ads API). Set this value to the customer ID of the data provider that updates the resources of the specified customer ID. It should be set without hyphens (`-`). To learn more about Linked Accounts, visit the [Help Center](https://support.google.com/google-ads/answer/7365001).
> [!NOTE]
> **Note:** For more detail on how to use them and any additional client library-specific environment variables, refer to the configuration guides that are dedicated to each client library: [Java](https://developers.google.com/google-ads/api/docs/client-libs/java/config-file), [.NET](https://developers.google.com/google-ads/api/docs/client-libs/dotnet/configuration), [PHP](https://developers.google.com/google-ads/api/docs/client-libs/php/configuration), [Python](https://developers.google.com/google-ads/api/docs/client-libs/python/configuration), [Ruby](https://developers.google.com/google-ads/api/docs/client-libs/ruby/configuration), [Perl](https://developers.google.com/google-ads/api/docs/client-libs/perl/configuration).
Environment variables are commonly defined in a bash configuration file such
as a `.bashrc` or `.bash_profile` file located in the `$HOME` directory. They
can also be defined using the command line.
> [!NOTE]
> **Note:** These instructions assume you're using Bash. If you're using a different shell, consult documentation for equivalent commands.
Here are some basic steps to define an environment variable using a `.bashrc`
file using a terminal:
# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc
# Update your bash environment to use the most recently updated
# version of your .bashrc file.
src ~/.bashrc
Environment variables can also be set in your terminal instance directly from
the command line:
export GOOGLE_ADS_CLIENT_ID=1234567890
Another alternative is to set environment variables when calling the command
that uses them:
GOOGLE_ADS_CLIENT_ID=1234567890 php /path/to/script/that/uses/envvar.php
## Fetch entities
[`GoogleAdsService.SearchStream`](https://developers.google.com/google-ads/api/reference/rpc/v24/GoogleAdsService/SearchStream)
is typically used to fetch entities, and the results are returned as a stream
of rows. Alternatively, you can use
[`GoogleAdsService.Search`](https://developers.google.com/google-ads/api/reference/rpc/v24/GoogleAdsService/Search) to fetch
entities over an unreliable internet connection. `GoogleAdsService.Search`
returns results as fixed page sizes of 10,000 rows per page.
Our client library automatically [implements paging](https://developers.google.com/google-ads/api/docs/reporting/paging)
when you iterate results so that you can sequentially download and process them
all at once.
### Java
```java
private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
try (GoogleAdsServiceClient googleAdsServiceClient =
googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
String query = "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id";
// Constructs the SearchGoogleAdsStreamRequest.
SearchGoogleAdsStreamRequest request =
SearchGoogleAdsStreamRequest.newBuilder()
.setCustomerId(Long.toString(customerId))
.setQuery(query)
.build();
// Creates and issues a search Google Ads stream request that will retrieve all campaigns.
ServerStream stream =
googleAdsServiceClient.searchStreamCallable().call(request);
// Iterates through and prints all of the results in the stream response.
for (SearchGoogleAdsStreamResponse response : stream) {
for (GoogleAdsRow googleAdsRow : response.getResultsList()) {
System.out.printf(
"Campaign with ID %d and name '%s' was found.%n",
googleAdsRow.getCampaign().getId(), googleAdsRow.getCampaign().getName());
}
}
}
}
```
### C#
```c#
public void Run(GoogleAdsClient client, long customerId)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
Services.V24.GoogleAdsService);
// Create a query that will retrieve all campaigns.
string query = @"SELECT
campaign.id,
campaign.name,
campaign.network_settings.target_content_network
FROM campaign
ORDER BY campaign.id";
try
{
// Issue a search request.
googleAdsService.SearchStream(customerId.ToString(), query,
delegate (SearchGoogleAdsStreamResponse resp)
{
foreach (GoogleAdsRow googleAdsRow in resp.Results)
{
Console.WriteLine("Campaign with ID {0} and name '{1}' was found.",
googleAdsRow.Campaign.Id, googleAdsRow.Campaign.Name);
}
}
);
}
catch (GoogleAdsException e)
{
Console.WriteLine("Failure:");
Console.WriteLine($"Message: {e.Message}");
Console.WriteLine($"Failure: {e.Failure}");
Console.WriteLine($"Request ID: {e.RequestId}");
throw;
}
}
```
### PHP
```php
public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
{
$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
// Creates a query that retrieves all campaigns.
$query = 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id';
// Issues a search stream request.
/** @var GoogleAdsServerStreamDecorator $stream */
$stream = $googleAdsServiceClient->searchStream(
SearchGoogleAdsStreamRequest::build($customerId, $query)
);
// Iterates over all rows in all messages and prints the requested field values for
// the campaign in each row.
foreach ($stream->iterateAllElements() as $googleAdsRow) {
/** @var GoogleAdsRow $googleAdsRow */
printf(
"Campaign with ID %d and name '%s' was found.%s",
$googleAdsRow->getCampaign()->getId(),
$googleAdsRow->getCampaign()->getName(),
PHP_EOL
);
}
}
```
### Python
```python
def main(client: GoogleAdsClient, customer_id: str) -> None:
ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService")
query: str = """
SELECT
campaign.id,
campaign.name
FROM campaign
ORDER BY campaign.id"""
# Issues a search request using streaming.
stream: Iterator[SearchGoogleAdsStreamResponse] = ga_service.search_stream(
customer_id=customer_id, query=query
)
for batch in stream:
rows: List[GoogleAdsRow] = batch.results
for row in rows:
print(
f"Campaign with ID {row.campaign.id} and name "
f'"{row.campaign.name}" was found.'
)
```
### Ruby
```ruby
def get_campaigns(customer_id)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client = Google::Ads::GoogleAds::GoogleAdsClient.new
responses = client.service.google_ads.search_stream(
customer_id: customer_id,
query: 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id',
)
responses.each do |response|
response.results.each do |row|
puts "Campaign with ID #{row.campaign.id} and name '#{row.campaign.name}' was found."
end
end
end
```
### Perl
```perl
sub get_campaigns {
my ($api_client, $customer_id) = @_;
# Create a search Google Ads stream request that will retrieve all campaigns.
my $search_stream_request =
Google::Ads::GoogleAds::V24::Services::GoogleAdsService::SearchGoogleAdsStreamRequest
->new({
customerId => $customer_id,
query =>
"SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id"
});
# Get the GoogleAdsService.
my $google_ads_service = $api_client->GoogleAdsService();
my $search_stream_handler =
Google::Ads::GoogleAds::Utils::SearchStreamHandler->new({
service => $google_ads_service,
request => $search_stream_request
});
# Issue a search request and process the stream response to print the requested
# field values for the campaign in each row.
$search_stream_handler->process_contents(
sub {
my $google_ads_row = shift;
printf "Campaign with ID %d and name '%s' was found.\n",
$google_ads_row->{campaign}{id}, $google_ads_row->{campaign}{name};
});
return 1;
}
```
### curl
> [!NOTE]
> **Note:** While a direct REST code sample for this step isn't provided here, you can achieve this using a manual REST request.
>
> Refer to the Google Ads API REST interface documentation and the method-specific reference pages. You will need to construct the JSON payload based on the proto definitions.
>
> Key Resources:
>
> - [Using REST](https://developers.google.com/google-ads/api/rest/overview)
> - [REST Interface Structure](https://developers.google.com/google-ads/api/rest/design/overview)
> - [JSON Field Mappings](https://developers.google.com/google-ads/api/rest/design/json-mappings)
> - Consult the [REST API Reference](https://developers.google.com/google-ads/api/reference/rpc/latest/overview) for the specific service and method.
## Code examples
[Check out our code examples](https://developers.google.com/google-ads/api/samples) of some common functions in the
Google Ads API.