Start using the Data Portability API

In this quickstart, you obtain an OAuth token for your account, and you send requests to the Data Portability API endpoints.

What you learn

In this quickstart you learn how to:

Send an authenticated request to the InitiatePortabilityArchive endpoint by providing a valid OAuth token. The response should contain a valid job_id.
Send an authenticated request to the GetPortabilityArchiveState endpoint. The response should contain a valid job state, and when the job is complete, a signed URL.
(Optional) Send an authenticated request with a valid OAuth token to the InitiatePortabilityArchive endpoint a second time using the same credentials. This returns a RESOURCE_EXHAUSTED error and is intended to highlight the importance of the ResetAuthorization endpoint.
Send an authenticated request to the ResetAuthorization endpoint. This request revokes all user-granted OAuth scopes.
(Optional) Send a request to the InitiatePortabilityArchive endpoint using the same OAuth token you used previously. The request should fail after the authorization is reset.

Prerequisites

To run this quickstart, you need to:

Verify that the Data Portability API is available to users in your location. For a list of supported countries and regions, see Common Questions on the "Share a copy of your data with a third party" page.
Complete the setup steps for the Data Portability API.
Follow the steps to configure OAuth for JavaScript web apps. In production, you would normally use a different flow like the OAuth flow for web server applications. For simplicity, this quickstart uses the JavaScript web app flow.
- When you create your authorization credentials, make a note of your OAuth 2.0 Client ID and your authorized redirect URI (for example, https://google.com). You need them later in the quickstart.
- When you configure scopes for the Data Portability API, note that this quickstart uses the myactivity.search resource group: https://www.googleapis.com/auth/dataportability.myactivity.search.
Obtain an OAuth token.
Obtain access to an account owned or controlled by your organization. This account's search activity data is exported in this quickstart.

Obtain an OAuth token

For this quickstart, you send an authorization request to obtain an OAuth token using a URL. This process uses the flow for JavaScript web apps. This flow does not return a refresh token.

For a production app, you would typically use an OAuth flow to obtain a refresh token that can be used to generate access tokens on demand. An example of this would be the flow for server-side web apps.

To obtain an OAuth token:

Compose a URL like the following.
```
https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=token&
scope=https://www.googleapis.com/auth/dataportability.myactivity.search&
state=developer-specified-value
```
In the URL:
- client_id is your OAuth client ID.
- redirect_uri is your authorized redirect URI; for example, https://google.com.
Notice that the scope used in the URL for this quickstart is the search activity scope. You can also use the YouTube activity scope or both scopes.

Warning: Do not mix Data Portability API scopes with other types of scopes or include previously granted scopes as this will result in errors. For details, see Scope restrictions.
Paste the URL into your browser's address bar, and follow the steps in the OAuth flow. This flow requires you to sign into the account owned or controlled by your organization that you're using for this quickstart.

This is the account that's consenting to the OAuth scopes. The consent screen should look like this (the text in your screen may vary from the text in this image):
After granting consent, you should be forwarded to the redirect URI— https://google.com. The URL that is generated in the address bar includes the OAuth access token.

For example, if the user account grants OAuth access to the dataportability.myactivity.search scope, the generated URL looks like this:
```
https://google.com/#state=developer-specified-value&access_token=<your_OAuth_token>&token_type=Bearer&expires_in=3599&scope=https://www.googleapis.com/auth/dataportability.myactivity.search
```
In the URL, <your_OAuth_token> is a string that represents the token.

Important: Your OAuth access token expires in one hour. If you need to generate a new token, follow the previous steps.

To validate the OAuth token, paste this URL into your browser:

https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=your_OAuth_token

The response should look like this:

{
  "azp": <your_azp_value>,
  "aud": <your_aud_value>,
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "exp": "1694210968",
  "expires_in": "3334",
  "access_type": "online"
}

Gather your OAuth token and your API key. You need these to make calls to the Data Portability API.

Send requests to the endpoints

In this quickstart you use curl commands to call the Data Portability API endpoints. These commands require the OAuth token and API key you gathered previously.

To call the Data Portability API:

First, you send an authenticated request to the InitiatePortabilityArchive endpoint. This request starts an archive job.

Run the following curl command:
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate
```
In the command:
- your_OAuth_token is your OAuth token.
Warning: The resources parameter should only contain the OAuth scopes that were granted access. In this example, only myactivity.search was granted. If you include additional resource groups, an error is returned. For details, see Scope restrictions.

The InitiatePortabilityArchive request returns a job_id. This job ID is used to retrieve the state of the data archive.
```
{
  "archiveJobId": "<your_job_id>"
}
```
If you fail to provide a valid OAuth token, this error message is returned:
```
Request had invalid authentication credentials. Expected OAuth 2.0 access
token, login cookie or other valid authentication credential. See
https://developers.google.com/identity/sign-in/web/devconsole-project.
```
Next, you send an authenticated request to the GetPortabilityArchiveState endpoint to retrieve the status of the archive job.

Run the following curl command:
```
curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/archiveJobs/your_job_id/portabilityArchiveState
```
In the command:
- your_OAuth_token is your OAuth token.
- your_job_id is the job ID returned by the InitiatePortabilityArchive request.
The response is based on the state of the job. If the job is not complete, the response provides the current state. You should send requests to this endpoint periodically until the job is complete.
```
{
  "state": "IN_PROGRESS"
}
```
If the job is complete, the response contains the state and one or more signed URLs that are used to download the data archive.
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
}
```
Paste the signed URL into your browser to download the data archive. You should examine the contents of the archive to ensure that it contains the expected search activity data.

Note: The amount of time required to complete the archive job depends on the archive's size. The maximum duration is seven days.
Note: If you receive a FAILED state in the response, you may retry the export using the RetryPortabilityArchive method.

(Optional) Repeat the previous command to send an authenticated request to the InitiatePortabilityArchive endpoint.

curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

In the command:

your_OAuth_token is your OAuth token.

The response should indicate that the one-time consent for the myactivity.search resource is exhausted for this user.

...
  "error":
    {
      "code": 429,
  "message": "Resource has been exhausted (check quota).",
  "status": "RESOURCE_EXHAUSTED"
}

Send an authenticated request to the ResetAuthorization endpoint. This request revokes all user-granted OAuth scopes and lets you call InitiatePortabilityArchive for a resource group that you've already used.
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/authorization:reset
```
In the command:
- your_OAuth_token is your OAuth token.
This command returns an empty response.

(Optional) After resetting authorization, send another request to the InitiatePortabilityArchive endpoint. Use the same curl command you used previously.

curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

In the command:

your_OAuth_token is your OAuth token.

The response should return an error because the OAuth token you provided was revoked.

...
  "error": {     
    "code": 401,    
        "message": "Request had invalid authentication credentials. Expected
        OAuth 2 access token, login cookie or other valid authentication
        credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
        "status": "UNAUTHENTICATED"
  }