# Google Mobile Data Plan Sharing API

## Motivation

The Google Mobile Data Plan Sharing API allows an operator to send information
about a user's (identified by [*user key*](https://developers.google.com/mobile-data-plan/establishing_cpid)) data plan to
GTAF. On this page, we outline the mechanism through which these updates can be
pushed to GTAF and thereby Google applications. The API currently allows the DPA
to send data plan status to GTAF to be consumed by a Google client.

## Authentication

All Data Plan Sharing API requests to GTAF must be authenticated using the
Google Cloud OAuth2 server. The requests must be authenticated as a service
account that has been whitelisted in the [ISP Portal](https://isp.google.com)
for the ASN the DPA represents. See [Google Cloud OAuth 2.0 for Service
Accounts](https://developers.google.com/identity/protocols/OAuth2ServiceAccount)
for documentation on how to use OAuth with Google Cloud service accounts.

## Data Plan Updates

Currently the Google Mobile Data Plan Sharing API allows an operator to share
updates about a user's data plan:

- **Data Plan Status:** Captures current status of a user's data plan. For example, if a user is running out of data, an operator can push a data plan status update to GTAF which could then be used by GTAF to send a plan status [notification](https://developers.google.com/mobile-data-plan/notifications) to the user.

## API Description

![](https://developers.google.com/static/mobile-data-plan/images/get_data_plan_overview.svg)
**Figure 3. GTAF-DPA interaction when DPA shares data plan status with GTAF.**

Applications can receive data plan status information shared with GTAF in one of
two ways:

1. UE calls GTAF for data plan status information:
   1. The operator's DPA uses the Data Plan Sharing API to push a user's data plan status to GTAF. GTAF stores the plan status and its associated *user key* until the expiration time specified by the operator.
   2. Google application running on UE requests the data plan status information using a Google-internal API. The application includes the *user key* in its request.
   3. If the application can use cached data plan status then GTAF uses the *user key* to look up the user's data plan status. GTAF then returns this status to the application.
2. GTAF pushes data plan status information to the UE:
   1. When relevant, data plan status received from the operator is directly pushed to the UE. In particular, the pushed plan status is used to update the on device cache of Mobile Data Plan module in Google Play Services.

### Sharing Data Plan Status

The DPA uses an HTTPS POST to create and update an existing plan status entry
for a user to be used by a client. Currently GTAF supports *mobiledataplan* and
*youtube* as valid client identifiers. Here is an example request for an
operator with asn 12345 and *user key abcdef* sharing plan information with GTAF
for *youtube* client:

POST
https://mobiledataplansharing.googleapis.com/v1/operators/12345/clients/youtube/users/abcdef/planStatus

The request body is an instance of
[PlanStatus](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#PlanStatus).

    {
      "plans": [{
        "planName": "ACME1",
        "planId": "1",
        "planCategory": "PREPAID",
        "expirationTime": "2017-01-29T01:00:03.14159Z", // req.
        "planModules": [{
          "moduleName": "Giga Plan", // req.
          "trafficCategories": ["GENERIC"],
          "expirationTime": "2017-01-29T01:00:03.14159Z", // req.
          "overUsagePolicy": "BLOCKED",
          "maxRateKbps": "1500",
          "description": "1GB for a month", // req.
          "coarseBalanceLevel": "HIGH_QUOTA"
        }]
      }],
      "planInfoPerClient": {
        "youtube": {
          "rateLimitedStreaming": {
            "maxMediaRateKbps": 569
          }
        }
      },
      "languageCode": "en-US", // req.
      "expireTime": "2018-06-14T08:41:27-07:00", // req.
      "updateTime": "2018-06-07T07:41:22-07:00", // req.
      "title": "Prepaid Plan"
    }

> [!NOTE]
> **Note:** The full format of Google Mobile Data Plan Sharing API requests is described in the [reference section](https://developers.google.com/mobile-data-plan/reference/rest/).

If the request is successful, GTAF will return HTTP response code 200 and the
pushed *planStatus* entry with a notifications entry if any notification was
sent to the user. If GTAF identifies a problem with the request, it will return
an HTTP status code in the range 400-499. If GTAF is unable to complete a
request due to a GTAF fault, GTAF will return an HTTP code in the range 500-599.
Requests that receive a response in the 500-599 range are considered retryable
and requests that receive a response in the 400-499 range are generally not
retryable. [Error Cases](https://developers.google.com/mobile-data-plan/dataplansharing_error_cases) explains the error
responses from GTAF in detail.

### Plan Status Push for Default Client

GTAF supports the following call where the plan status is pushed by the operator
without specifying the client for which it can be used. In this case, we assume
that the plan status is intended for *mobiledataplan* client and the operator
intends to send a notification to the user. The request body is an instance of
[PlanStatus](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#PlanStatus)

POST
https://mobiledataplansharing.googleapis.com/v1/operators/12345/planStatuses?userKey=abcdef

### Internationalization

In order to support internationalization, the DPA must know the user's preferred
language even without a direct request from GTAF. To solve this issue the
request to the CPID endpoint MAY include an Accept-Language header depending on
the clients access to user language preferences. If the header is included then
human readable strings in updates that the DPA sends using the MDP API must use
the settings provided in the CPID request.

The DPA MAY update user language preferences when it gets a request from GTAF
with an Accept-Language header and use the updated user preferences to determine
the language code in future requests to GTAF.

The DPA MUST specify the language used for user visible strings using
*languageCode*. GTAF uses this to construct the title and the body of
notifications shown to the user.