Yahoo! JAPAN Ads API | Developer Center

API Call

After adding the application, please make an API call. You can check whether it returns an expected response by sending a request to Yahoo! JAPAN Ads API.

The endpoints used for the API call are as follows.

Type	URI
Authorization API	https://biz-oauth.yahoo.co.jp/oauth
Search Ads API	https://ads-search.yahooapis.jp/api
Display Ads API	https://ads-display.yahooapis.jp/api

The entities obtained on adding the application process and the entities obtained on the API call procedure need to be set for each parameter.
The details of each parameter are as follows.

Parameter name	Description
client_id	A client ID for the added application. Enter the ID for the application at the part of "CLIENT_ID" in the sample code.
client_secret	A client secret of the added application. Enter the client secret for the application at the part of "CLIENT_SECRET" in the sample code.
redirect_uri	A redirect URI is entered on adding the application. Enter the redirect URI for the application at the part of "REDIRECT_URI" in the sample code. You can enter half-width alphanumeric characters and the following symbols for the redirect URI. Additionally, the parameter must be URL encoded properly. ! # % & + - . / : ; = ? @ _ ~
code	An authorization code that is acquired during the steps of the API call. Enter the authorization code for the application at the part of "AUTH_CODE" in the sample code.
access_token	An access token that is acquired through the steps of an API call. Enter the access token for the application at the part of "ACCESS_TOKEN" in the sample code.
refresh_token	Refresh token that is acquired during the steps of API call. Enter the refresh token for the application at the part of "REFRESH_TOKEN" in the sample code.
state	A parameter that is available when requesting authorization. Set a unique and random string (max. 512 characters) that is hard to discriminate. You can enter half-width alphanumeric characters and the following symbols for the state parameter. Additionally, the parameter must be URL encoded properly. ! # % & + - . / : ; = ? @ _ ~

Steps for API call

1. Redirect to the authorization screen to be authorized by application users.
Set client ID and redirect URI to the endpoint (Authentication API) parameters.
And for security, specifying the state parameter on request is recommended. Set a unique and random string on a state parameter to identify the authentication request and response from the authentication server uniquely.
Available values on the state parameter can be referred to in "RFC6749 Appendix A.5" (external website).


https://biz-oauth.yahoo.co.jp/oauth/v1/authorize?response_type=code
&client_id=CLIENT_ID
&redirect_uri=REDIRECT_URI
&scope=yahooads
&state=THIS_VALUE_SHOULD_BE_UNIQUE_PER_REQUEST

2. The authorization view appears when you sign in with your Business ID that has access to the ad account. To use the application, click [Approve].
Learn about "About OAuth2.0".

3. If the application user approves, it redirects to the redirect URI set as endpoint, and the authorization code ("code") is passed.
The authorization code expires in 10 minutes. Obtain the code again if it's expired.
If the specified state parameter on step 1, please check whether the value specified for state and the value on the state query parameter included in the redirect response URI are the same or not.

4. Send a request to the authentication API using the authorization code.
Set the client ID, client secret, redirect URI, and authorization code that you obtained in step 3 as parameters.


https://biz-oauth.yahoo.co.jp/oauth/v1/token?grant_type=authorization_code
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
&redirect_uri=REDIRECT_URI
&code=AUTH_CODE

5. Access token and refresh token returned as a response.
The access token expires in 1 hour after issued.


{"access_token":"ACCESS_TOKEN",
"expires_in":"3600",
"token_type":"Bearer",
"refresh_token":"REFRESH_TOKEN"}

6. Including the obtained access token in the HTTP header, send an API call to Yahoo! JAPAN Ads API.
When "200" returns in the HTTP status code on the response, the call has succeeded.


Authorization: Bearer "ACCESS_TOKEN"

In addition to the access token, all services generally require including accounts that the Business ID has direct access to in the HTTP header as the base.
You can get the available account IDs for the base account by using BaseAccountService/get.


x-z-base-account-id: "BASE_ACCOUNT_ID"

Learn about account ID being specified as base account.

[Reduce your development workload]
You can generate a client in any programming language by reading the following yaml file using the OpenAPI Generator, etc.

The OpenAPI interface of Yahoo! JAPAN Ads API is disclosed for developers.
　- Search Ads API
　- Display Ads API

Refer to the following information about OpenAPI.
　OpenAPI

More information to help you develop the API is available on the following pages:
　- Developers Guide
　- Reference
　- Sample Program

Note: Access token
Obtain a new access token by using the refresh token if it has expired.
The refresh token is valid until the user cancels approval of the application.


https://biz-oauth.yahoo.co.jp/oauth/v1/token?grant_type=refresh_token
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
&refresh_token=REFRESH_TOKEN

A new access token is returned as a response.


{"access_token":"ACCESS_TOKEN",
"expires_in":3600,
"token_type":"Bearer"}

Note: Revoke the token
You can specify and revoke a certain access token or refresh token that you obtained.
When you revoke an authorization for any application user, etc.
You can revoke a specific token by an HTTP POST request to the URL for revoking the token. Access token and refresh token can be specified with the token parameter in "application/x-www-form-urlencoded" format.
The following sample is for the case of using the curl command.
*Replace each "\" symbol at the line end with a backslash" (half-width)


curl https://biz-oauth.yahoo.co.jp/oauth/v1/revoke \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "token=TOKEN"

When the request succeeds, it will respond the HTTP status code "200".

Developer Center

Related sites: