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.

TypeURI
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 nameDescription
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.
! # % & + - . / : ; = ? @ _ ~ 
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.
! # % & + - . / : ; = ? @ _ ~ 


Follow the steps below.

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. On the authorization screen, your application user clicks [Approve].



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"


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

■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".