Looker Studio Community Connector API

openapi: 3.1.0
info:
  title: Looker Studio Community Connector API
  description: >-
    Build custom data connectors to bring data from any source into Looker
    Studio. Connectors are built using Google Apps Script and implement three
    core functions: getConfig(), getSchema(), and getData(). This specification
    documents the contract between Looker Studio and community connectors,
    defining the request and response formats for each required function.
  version: v1
  contact:
    name: Google
    url: https://developers.google.com/looker-studio/connector
  license:
    name: Google APIs Terms of Service
    url: https://developers.google.com/terms
  termsOfService: https://developers.google.com/terms
externalDocs:
  description: Looker Studio Community Connector Documentation
  url: https://developers.google.com/looker-studio/connector/reference
servers:
  - url: https://datastudio.google.com/datasources/create
    description: Looker Studio data source creation endpoint
tags:
  - name: Authentication
    description: >-
      Operations for managing third-party authentication including OAuth2, API
      keys, and username/password credentials.
  - name: Configuration
    description: >-
      Operations related to connector configuration, including user-configurable
      options and authentication setup.
  - name: Data
    description: >-
      Operations for fetching data from the external source and returning it to
      Looker Studio.
  - name: Schema
    description: >-
      Operations for defining the data structure and field definitions returned
      by the connector.
paths:
  /connector/getAuthType:
    post:
      operationId: getAuthType
      summary: Looker Studio Get authentication type
      description: >-
        Returns the authentication type required by the connector. Looker Studio
        calls this function to determine how to authenticate the user with the
        third-party data source. The connector must return one of the supported
        authentication types.
      tags:
        - Authentication
      requestBody:
        required: false
        description: Empty request body. No parameters are needed.
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The authentication type configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTypeResponse'
  /connector/isAuthValid:
    post:
      operationId: isAuthValid
      summary: Looker Studio Validate authentication credentials
      description: >-
        Validates the current third-party authentication credentials. Looker
        Studio calls this function to check whether the user's stored
        credentials are still valid before making data requests.
      tags:
        - Authentication
      requestBody:
        required: false
        description: Empty request body. Credentials are accessed from the script's properties.
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Whether the credentials are valid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                    description: True if the stored credentials are valid.
  /connector/setCredentials:
    post:
      operationId: setCredentials
      summary: Looker Studio Store authentication credentials
      description: >-
        Stores the user's authentication credentials for the third-party data
        source. Looker Studio calls this function after the user provides their
        credentials through the authentication UI.
      tags:
        - Authentication
      requestBody:
        required: true
        description: The credentials to store for the third-party service.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetCredentialsRequest'
      responses:
        '200':
          description: Result of the credential storage operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetCredentialsResponse'
  /connector/getConfig:
    post:
      operationId: getConfig
      summary: Looker Studio Get connector configuration options
      description: >-
        Returns the user-configurable options for the connector. Looker Studio
        displays these options to the user when setting up a data source. The
        configuration can include text inputs, dropdowns, checkboxes, and
        informational text. Supports stepped configuration where subsequent
        config options depend on previous selections.
      tags:
        - Configuration
      requestBody:
        required: true
        description: The request containing language preference and any previously set config parameters.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetConfigRequest'
      responses:
        '200':
          description: The connector configuration definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetConfigResponse'
  /connector/getSchema:
    post:
      operationId: getSchema
      summary: Looker Studio Get data schema
      description: >-
        Returns the schema (field definitions) for the data that the connector
        provides. Each field includes an ID, name, data type, semantic type, and
        whether it is a dimension or metric. Looker Studio uses this schema to
        understand the structure of the available data.
      tags:
        - Schema
      requestBody:
        required: true
        description: The request containing configuration parameters set by the user.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetSchemaRequest'
      responses:
        '200':
          description: The data schema with field definitions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSchemaResponse'
  /connector/getData:
    post:
      operationId: getData
      summary: Looker Studio Get data rows
      description: >-
        Fetches tabular data from the external source matching the request
        criteria. Receives configuration parameters, optional date ranges,
        requested field names, and dimension filters. Returns rows with values
        in the schema-defined order. Limited to 1 million rows per request.
      tags:
        - Data
      requestBody:
        required: true
        description: >-
          The request specifying which fields to retrieve, optional date range,
          and any filters to apply.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetDataRequest'
      responses:
        '200':
          description: The data rows matching the request criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDataResponse'
components:
  schemas:
    AuthType:
      type: string
      description: The type of authentication used by the connector.
      enum:
        - NONE
        - OAUTH2
        - KEY
        - USER_PASS
        - USER_TOKEN
        - PATH_USER_PASS
        - PATH_KEY
    AuthTypeResponse:
      type: object
      description: Response from getAuthType containing the authentication configuration.
      properties:
        type:
          $ref: '#/components/schemas/AuthType'
        helpUrl:
          type: string
          format: uri
          description: Optional URL to help documentation for authentication setup.
    SetCredentialsRequest:
      type: object
      description: Request to store credentials for the third-party service.
      properties:
        userPass:
          type: object
          description: Username and password credentials.
          properties:
            username:
              type: string
            password:
              type: string
        userToken:
          type: object
          description: Username and token credentials.
          properties:
            username:
              type: string
            token:
              type: string
        key:
          type: string
          description: API key credential.
        pathUserPass:
          type: object
          description: Path, username, and password credentials.
          properties:
            path:
              type: string
            username:
              type: string
            password:
              type: string
        pathKey:
          type: object
          description: Path and API key credentials.
          properties:
            path:
              type: string
            key:
              type: string
    SetCredentialsResponse:
      type: object
      description: Response from setCredentials.
      properties:
        errorCode:
          type: string
          description: Error code if credentials are invalid. Returns NONE on success.
          enum:
            - NONE
            - INVALID_CREDENTIALS
    GetConfigRequest:
      type: object
      description: Request for connector configuration options.
      properties:
        languageCode:
          type: string
          description: The user's language preference (ISO 639 code).
        configParams:
          type: object
          description: >-
            Previously configured parameters. Present during stepped
            configuration when the user has already filled in some options.
          additionalProperties:
            type: string
    GetConfigResponse:
      type: object
      description: Response containing the connector's configurable options.
      properties:
        configParams:
          type: array
          description: The list of configuration elements to display to the user.
          items:
            $ref: '#/components/schemas/ConfigParam'
        dateRangeRequired:
          type: boolean
          description: >-
            Whether the connector requires a date range to be specified by the
            user. Defaults to false.
        isSteppedConfig:
          type: boolean
          description: >-
            Whether the connector uses stepped configuration where subsequent
            options depend on previous selections. Defaults to false.
    ConfigParam:
      type: object
      description: A single configuration parameter definition.
      properties:
        type:
          type: string
          description: The type of UI element to render.
          enum:
            - TEXTINPUT
            - TEXTAREA
            - SELECT_SINGLE
            - SELECT_MULTIPLE
            - CHECKBOX
            - INFO
        name:
          type: string
          description: The unique identifier for this parameter.
        displayName:
          type: string
          description: The label displayed to the user.
        helpText:
          type: string
          description: Help text shown below the input element.
        placeholder:
          type: string
          description: Placeholder text for text input elements.
        isDynamic:
          type: boolean
          description: Whether this parameter triggers a re-fetch of config when changed.
        options:
          type: array
          description: Available options for SELECT_SINGLE and SELECT_MULTIPLE types.
          items:
            type: object
            properties:
              label:
                type: string
                description: Display label for the option.
              value:
                type: string
                description: The value submitted when this option is selected.
    GetSchemaRequest:
      type: object
      description: Request for the connector's data schema.
      properties:
        configParams:
          type: object
          description: The user-configured parameters.
          additionalProperties:
            type: string
    GetSchemaResponse:
      type: object
      description: Response containing the data schema.
      properties:
        schema:
          type: array
          description: The list of field definitions.
          items:
            $ref: '#/components/schemas/Field'
    Field:
      type: object
      description: Defines a single field in the connector's data schema.
      properties:
        name:
          type: string
          description: The unique identifier for the field.
        label:
          type: string
          description: The display name for the field.
        description:
          type: string
          description: A description of the field's contents.
        dataType:
          type: string
          description: The data type of the field values.
          enum:
            - STRING
            - NUMBER
            - BOOLEAN
        semantics:
          $ref: '#/components/schemas/FieldSemantics'
        group:
          type: string
          description: An optional group name for organizing related fields.
        formula:
          type: string
          description: An optional calculated field formula.
        isDefault:
          type: boolean
          description: Whether this field is included by default in new charts.
        defaultAggregationType:
          type: string
          description: The default aggregation type for metric fields.
          enum:
            - AVG
            - COUNT
            - COUNT_DISTINCT
            - MAX
            - MIN
            - SUM
            - AUTO
            - NONE
        isHidden:
          type: boolean
          description: Whether the field is hidden from the user interface.
    FieldSemantics:
      type: object
      description: Semantic information about a field.
      properties:
        conceptType:
          type: string
          description: Whether the field is a dimension or metric.
          enum:
            - DIMENSION
            - METRIC
        semanticType:
          type: string
          description: >-
            The semantic type describing the meaning of the field values. Common
            types include TEXT, NUMBER, BOOLEAN, YEAR, YEAR_MONTH_DAY, PERCENT,
            CURRENCY_USD, COUNTRY, CITY, and LATITUDE_LONGITUDE among others.
          enum:
            - TEXT
            - NUMBER
            - BOOLEAN
            - PERCENT
            - CURRENCY_USD
            - CURRENCY_EUR
            - CURRENCY_GBP
            - CURRENCY_JPY
            - YEAR
            - YEAR_QUARTER
            - YEAR_MONTH
            - YEAR_MONTH_DAY
            - YEAR_MONTH_DAY_HOUR
            - YEAR_MONTH_DAY_SECOND
            - QUARTER
            - MONTH
            - WEEK
            - DAY_OF_WEEK
            - HOUR
            - MINUTE
            - DURATION
            - COUNTRY
            - COUNTRY_CODE
            - CONTINENT
            - CONTINENT_CODE
            - SUB_CONTINENT
            - SUB_CONTINENT_CODE
            - REGION
            - REGION_CODE
            - CITY
            - CITY_CODE
            - METRO
            - METRO_CODE
            - LATITUDE_LONGITUDE
            - URL
        semanticGroup:
          type: string
          description: The semantic group for the field.
        isReaggregatable:
          type: boolean
          description: Whether the metric can be re-aggregated.
    GetDataRequest:
      type: object
      description: Request for fetching data rows from the connector.
      properties:
        configParams:
          type: object
          description: The user-configured parameters.
          additionalProperties:
            type: string
        dateRange:
          type: object
          description: The date range for the data request if dateRangeRequired is true.
          properties:
            startDate:
              type: string
              format: date
              description: Start date in YYYY-MM-DD format.
            endDate:
              type: string
              format: date
              description: End date in YYYY-MM-DD format.
        fields:
          type: array
          description: The list of field names to include in the response.
          items:
            type: object
            properties:
              name:
                type: string
                description: The field name as defined in the schema.
        dimensionFilters:
          type: array
          description: Filters to apply to dimension fields.
          items:
            $ref: '#/components/schemas/DimensionFilter'
    DimensionFilter:
      type: object
      description: A filter applied to a dimension field.
      properties:
        fieldName:
          type: string
          description: The name of the dimension field to filter.
        values:
          type: array
          description: The values to filter by.
          items:
            type: string
        type:
          type: string
          description: The filter operator type.
          enum:
            - EQUALS
            - CONTAINS
            - REGEXP_PARTIAL_MATCH
            - REGEXP_EXACT_MATCH
            - IN_LIST
            - IS_NULL
            - BETWEEN
            - NUMERIC_GREATER_THAN
            - NUMERIC_GREATER_THAN_OR_EQUAL
            - NUMERIC_LESS_THAN
            - NUMERIC_LESS_THAN_OR_EQUAL
        operator:
          type: string
          description: The logical operator for combining multiple filter conditions.
          enum:
            - AND
            - OR
    GetDataResponse:
      type: object
      description: Response containing the requested data rows.
      properties:
        schema:
          type: array
          description: >-
            The field definitions for the returned data, in the order they
            appear in each row.
          items:
            $ref: '#/components/schemas/Field'
        rows:
          type: array
          description: The data rows. Each row contains values in schema-defined order.
          items:
            type: object
            properties:
              values:
                type: array
                description: >-
                  The field values for this row in the same order as the schema
                  fields.
                items:
                  oneOf:
                    - type: string
                    - type: number
                    - type: boolean
        filtersApplied:
          type: boolean
          description: Whether the connector applied the requested filters.