Yahoo! JAPAN Ads API | Developer Center

API Call

After adding 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 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 application process and the entities obtained on API call procedure are need to be set to each parameter.
The details of each parameter are as follows.

Parameter name	Description
client_id	A client ID of added application. Enter the ID for the application at the part of "CLIENT_ID" in the sample code.
client_secret	A client secret of added application. Enter the client secret for the application at the part of "CLIENT_SECRET" in the sample code.
redirect_uri	A redirect URI entered on adding 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 following symbols for redirect URI. Additionally, the parameter must be URL encoded properly. ! # % & + - . / : ; = ? @ _ ~
code	Authorization code that is acquired on the steps of API call. Enter the authorization code for the application at the part of "AUTH_CODE" in the sample code.
access_token	Access token that is acquired on the steps of 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 on 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 an unique and random string (max. 512 characters) that is hard to be discriminated. You can enter half-width alphanumeric characters and following symbols for state parameter. Additionally, the parameter must be URL encoded properly. ! # % & + - . / : ; = ? @ _ ~

Steps for API call

1. Redirect to authorization screen to be authorized by application users.
Set client ID and redirect URI to the endpoint (Authentication API) parameters.
And for security, specifying state parameter on request is recommended. Set an unique and random string on state parameter to identify the authentication request and response from authentication server uniquely.
Available values on state parameter can be referred on "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 Yahoo! JAPAN Business ID that has access to the ad account. To use the application, click [Approve].
Learn about "About OAuth2.0".

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

4. Send a request to 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 return 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 obtained access token in HTTP header, send an API call to Yahoo! JAPAN Ads API.
When "200" returns in HTTP status code on response, the call has succeeded.


Authorization: Bearer "ACCESS_TOKEN"

In addition to the access token, all services generally require including accounts that the Yahoo! JAPAN Business ID has direct access to in the HTTP header as the base.
You can get the available account IDs for 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 new access token by using refresh token if it's expired.
The refresh token is valid until the user cancel 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 returns as a response.


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

Note: Revoke 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 HTTP POST request to the URL for revoking token. Access token and refresh token can be specified with token parameter in "application/x-www-form-urlencoded" format.
Following sample is for the case of using curl command.
*Replace each "\" symbol at the line end with "a back slush" (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: