openapi: 3.2.0
info:
  version: '2.0'
  title: GMD API v2.0 Descriptors API
  description: 'Gracenote Music API Specification

    GMD API V2.0'
servers:
- url: /proxy/gmd/v2
tags:
- name: Descriptors
paths:
  /descriptorCorrelations/{descriptorType}:
    get:
      tags:
      - Descriptors
      parameters:
      - $ref: '#/components/parameters/apiKeyParam'
      - $ref: '#/components/parameters/condensedDescriptorType'
      - $ref: '#/components/parameters/categoryIds'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
                  data:
                    type: array
                    nullable: false
                    items:
                      $ref: '#/components/schemas/DescriptorCorrelationObject'
                required:
                - meta
                - data
        '400':
          $ref: '#/components/responses/ErrorResponse400'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
      description: 'The descriptor correlation API enables the computation of Artist and Recording similarity by providing numerical values representing that similarity. These similarity values can be used to inform music discovery and catalog navigation models and algorithms.


        The following workflow illustrates how correlates are used to show that the genre **Psychedelic Rock** is more similar to **Post-Modern Rock** than it is to **Ragtime**.


        1. The `/descriptors/genre` API is used to determine that the `genreID` for "Psychedelic Rock" is `2844`.


        ```

        curl https:///descriptors/genre

        ...

        {

        {

        "ID": "2844",

        "genericName": "Psychedelic Rock"

        }

        ...

        },


        ```


        2. The `/descriptors/descriptorCorrelations` API is used with `genreID` value `2844` and the descriptor type set to "genres".


        ```

        curl https:///descriptorCorrelations/genres?ids=2844

        ...

        {

        {

        "ID": "33121",

        "genre": "Post-Modern Rock",

        "weight": "200"

        },

        {

        "ID": "3128",

        "genre": "Ragtime",

        "weight": "-700"

        }

        ...

        }

        ```


        3. The results show that **Post-Modern Rock** is correlated to **Psychedelic Rock** with a weight of **200** while **Ragtime** is correlated with weight of **-700**. Therefore, **Post-Modern Rock** is the most similar genre.'
      summary: Calculate Artist and Recording similarity
      operationId: getDescriptorCorrelationsByDescriptorType
      x-operation-id-source: derived
components:
  responses:
    ErrorResponse400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              value:
                status: 400
                error: invalid_query_parameter_value
                description: 'Data Type Error: explicitLanguage must be of type boolean.'
    ErrorResponse404:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              value:
                status: 404
                error: resource_not_found
                description: Parameter given is not found.
  parameters:
    categoryIds:
      name: ids
      in: query
      required: true
      description: Comma seperated list of category ids (max 100)
      schema:
        type: string
    apiKeyParam:
      name: GN-APIKEY
      in: header
      description: API key to authorize the request.
      required: true
      schema:
        type: string
        examples:
        - your-api-key
    condensedDescriptorType:
      name: descriptorType
      in: path
      required: true
      description: Gracenote descriptor type.
      schema:
        type: string
        enum:
        - eras
        - moods
        - styles
        - tempos
        - artistTypes
        - genres
        - origins
  schemas:
    DescriptorCorrelationObject:
      type: object
      properties:
        ID:
          type: string
        descriptorType:
          type: string
        correlations:
          type: array
          items:
            $ref: '#/components/schemas/CorrelationObject'
    ResponseMeta:
      type: object
      nullable: false
      additionalProperties: false
      properties:
        total:
          type: integer
          nullable: false
        count:
          type: integer
          nullable: false
        offset:
          type: integer
          nullable: false
        references:
          type: object
          properties:
            genreCategories:
              type: string
            categoriesLanguage:
              type: string
      required:
      - total
      - count
      - offset
    CorrelationObject:
      type: object
      properties:
        ID:
          type: string
        name:
          type: string
        correlationValue:
          type: integer
        links:
          type: object
          properties:
            descriptorCorrelations:
              description: Only visible to Customers with GMD:Advanced Discovery package and above. will be of the type /descriptorCorrelations/{descriptorType}?id=ID
              type: string
    ErrorResponse:
      type: object
      nullable: false
      additionalProperties: false
      properties:
        status:
          type: integer
          nullable: false
        error:
          type: string
          nullable: false
        description:
          type: string
          nullable: false
      required:
      - status
      - error
      - description