API call structure

This guide describes the elements of an API call and demonstrates how to make some basic calls with cURL. cURL is a command line tool and library for the transfer of data with URLs.

The Waze Ads Management API is an API that uses REST bindings.

Create the body of the request as a JSON object.
Send it to the server with HTTP 1.1.
Deserialize the response as a JSON object.
Interpret the results.

Endpoint

The following URL is the Waze Ads Management API server endpoint where all requests are sent:

https://ads.wazeapis.com

API call examples

The examples in the following section demonstrate how to interact with the API with cURL. Although cURL is impractical to use to build a real-world application, the examples demonstrate how the Waze Ads Management API functions.

Note: Before you make a cURL call, you must complete the prerequisites in the Quickstart section. You must also obtain a WAZE_ACCESS_TOKEN as shown in the First Call section.

Example cURL call: Health check

The following is a basic example cURL call to check that the API is available:

curl -X GET https://ads.wazeapis.com/v1/health?key=API_KEY

The request URL consists of three parts, which are the endpoint, the method name, and the request parameters. The following information defines each part:

The endpoint:
```
https://ads.wazeapis.com
```
The method name:
```
v1/health
```
Request parameters:
In the example there's only one parameter, which is the API key:
```
key=API_KEY
```

Response

After the API server processes your request, the server returns a response that contains the JSON data that indicates whether the API is available. The following is an example of the Waze Ads Management API server response:

{
 "status": "SERVING"
}

Note: If the API isn't up, the status is NOT_SERVING instead of SERVING.

Example cURL call: Get Account

The following is an example cURL call to get information for a specific Account:

curl -X GET https://ads.wazeapis.com/v1/accounts/ACCOUNT_ID?key=API_KEY \
  -H "Authorization: Bearer WAZE_ACCESS_TOKEN"

Note: When you compare this to the health check cURL call, the method name is changed and this method requires authentication with a WAZE_ACCESS_TOKEN.

This cURL call has the following three components:

The request URL
The request header
The response

The three components of the cURL call are defined in the following list:

Request URL

The request URL consists of three parts, which are the endpoint, the method name, and the request parameters. The following information defines each part:

The endpoint:
```
https://ads.wazeapis.com
```
The method name and account ID:
You must include the full path to a method.
```
v1/accounts/ACCOUNT_ID
```
The request parameters:
In the example, there's only one parameter, which is the API key:
```
key=API_KEY
```

Request header

These are the HTTP headers that accompany the body in the request.

In the example, the main header is the WAZE_ACCESS_TOKEN as a Bearer token for authenticated calls.

Authorization: Bearer WAZE_ACCESS_TOKEN

Response

After the Waze Ads Management API server processes your request, it returns a response that contains the JSON data with the Account information, such as title, state, account type, and payment method.

{
 "name": "accounts/108404",
 "type": "LOCAL_STARTER",
 "createTime": "2020-08-14",
 "title": "Louisville Restaurant",
 "state": "ACTIVE",
 "category": "RESTAURANT",
 "payment": {
   "currencyCode": "USD",
   "method": "INVOICE"
 },
 "advertisingRegionCode": "US"
}

Example cURL call: Update Account

The following is an example cURL call to update the title of a specific Account:

curl -X PATCH https://ads.wazeapis.com/v1/accounts/ACCOUNT_ID?key=API_KEY&updateMask=title \
  -H "Authorization: Bearer WAZE_ACCESS_TOKEN"
  -d '{
    title: "Louisville Diner"
  }'

In this case, the request parameters of this cURL are:

key=API_KEY.
The updateMask, which is a field mask that tells the Waze Ads API which resource fields to modify.