google-ads-pb

Google Ads API Client Library for Golang

This library provides a Golang client for the Google Ads API. It's fully generated from the googleapis repository. More information on the generation process can be found here.

Although this project isn't official, we deem it as low-risk due to its maturity and our many years of using it in production. However, always consult the sunset schedule of the Google Ads API.

Features

• Full support for Google Ads API.
• Support for gRPC and REST Interface.
• Source code generated from the official googleapis repository.

Version support

Requirements

• Go 1.23
• Familiarize yourself with the OAuth2 guide.
• If needed, obtain a developer token.

Installation

go get github.com/shenzhencenter/google-ads-pb

Getting started

1. Prepare ACCESS_TOKEN, DEVELOPER_TOKEN, and CUSTOMER_ID.

Tips: For testing purposes, you can use google/oauth2l to obtain an access token.

1. gRPC example.

var (
    customerID     = os.Getenv("CUSTOMER_ID")
    developerToken = os.Getenv("DEVELOPER_TOKEN")
    accessToken    = os.Getenv("ACCESS_TOKEN")
)

cred := grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(nil, ""))
conn, err := grpc.NewClient("googleads.googleapis.com:443", cred)
if err != nil {
    panic(err)
}
defer conn.Close()

ctx := context.Background()
headers := metadata.Pairs(
    "authorization", "Bearer "+accessToken,
    "developer-token", developerToken,
    "login-customer-id", customerID,
)
ctx = metadata.NewOutgoingContext(ctx, headers)

req := &services.SearchGoogleAdsRequest{
    CustomerId: customerID,
    Query: "SELECT user_list.name, user_list.resource_name FROM user_list",
}
svc := services.NewGoogleAdsServiceClient(conn)
var header metadata.MD
result, err := svc.Search(ctx, req, grpc.Header(&header))
requestId := header.Get("request-id")
log.Printf("request-id: %v, login-customer-id: %v", requestId[0], customerID)
if err != nil {
    apiErr := status.Convert(err)
    log.Fatalf("code: %s, message: %s, details: %v", apiErr.Code(), apiErr.Message(), apiErr.Details())
}

for _, row := range result.Results {
    if row.UserList == nil {
        continue
    }
    log.Print("resource_name: ", row.UserList.GetResourceName(), " name: ", row.UserList.GetName())
}

1. HTTP example.

var (
    customerID     = os.Getenv("CUSTOMER_ID")
    developerToken = os.Getenv("DEVELOPER_TOKEN")
    accessToken    = os.Getenv("ACCESS_TOKEN")
)

var endpoint = fmt.Sprintf("https://googleads.googleapis.com/v18/customers/%s/googleAds:search", customerID)
req := services.SearchGoogleAdsRequest{
    Query: "SELECT user_list.name, user_list.resource_name FROM user_list",
}
reqBody, _ := protojson.Marshal(&req)

reqHttp, _ := http.NewRequest("POST", endpoint, bytes.NewReader(reqBody))
header := make(http.Header)
header.Set("content-type", "application/json")
header.Set("authorization", "Bearer "+accessToken)
header.Set("developer-token", developerToken)
header.Set("login-customer-id", customerID)
reqHttp.Header = header

httpResp, err := http.DefaultClient.Do(reqHttp)
if os.Getenv("DEBUG") != "" {
    reqId := httpResp.Header.Get("request-id")
    log.Print("request-id: ", reqId, " login-customer-id: ", reqHttp.Header.Get("login-customer-id"))
}
if err != nil {
    log.Panic(err)
}
defer httpResp.Body.Close()
var httpRespBody []byte
if httpRespBody, err = io.ReadAll(httpResp.Body); err != nil {
    log.Panic(err)
}
result := new(services.SearchGoogleAdsResponse)
if err := protojson.Unmarshal(httpRespBody, result); err != nil {
    log.Fatal("failed to unmarshal response: ", err, "response: ", string(httpRespBody))
}
for _, row := range result.Results {
    if row.UserList == nil {
        continue
    }
    log.Print("resource_name: ", row.UserList.GetResourceName(), " name: ", row.UserList.GetName())
}

References

• Google APIs
• Google Ads API Client Library for PHP
• google/oauth2l
• How to Use a Service Account to Call the Google Ads API with Golang

Contributing

As this project is fully protoc-generated, we aren't accepting pull requests. However, we value your feedback and suggestions, so feel free to open an issue.