Skip to main content
GET
/
library
/
matches
PlexGO
package main

import(
	"context"
	"github.com/LukeHagar/plexgo/models/components"
	"github.com/LukeHagar/plexgo"
	"github.com/LukeHagar/plexgo/models/operations"
	"log"
)

func main() {
    ctx := context.Background()

    s := plexgo.New(
        plexgo.WithAccepts(components.AcceptsApplicationXML),
        plexgo.WithClientIdentifier("abc123"),
        plexgo.WithProduct("Plex for Roku"),
        plexgo.WithVersion("2.4.1"),
        plexgo.WithPlatform("Roku"),
        plexgo.WithPlatformVersion("4.3 build 1057"),
        plexgo.WithDevice("Roku 3"),
        plexgo.WithModel("4200X"),
        plexgo.WithDeviceVendor("Roku"),
        plexgo.WithDeviceName("Living Room TV"),
        plexgo.WithMarketplace("googlePlay"),
        plexgo.WithSecurity("<YOUR_API_KEY_HERE>"),
    )

    res, err := s.Library.GetLibraryMatches(ctx, operations.GetLibraryMatchesRequest{
        Type: components.MediaTypeTvShow.ToPointer(),
        IncludeFullMetadata: components.BoolIntTrue.ToPointer(),
        IncludeAncestorMetadata: components.BoolIntTrue.ToPointer(),
        IncludeAlternateMetadataSources: components.BoolIntTrue.ToPointer(),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.MediaContainerWithMetadata != nil {
        // handle response
    }
}
{
  "MediaContainer": {
    "identifier": "<string>",
    "offset": 123,
    "size": 123,
    "totalSize": 123,
    "Metadata": [
      {
        "title": "<string>",
        "type": "<string>",
        "addedAt": 123,
        "key": "<string>",
        "absoluteIndex": 123,
        "art": "/library/metadata/58683/art/1703239236",
        "audienceRating": 5,
        "audienceRatingImage": "<string>",
        "Autotag": [
          {
            "tag": "Shaun Lawton",
            "confidence": 123,
            "context": "<string>",
            "filter": "actor=49",
            "id": 123,
            "ratingKey": "58683",
            "role": "Secretary",
            "tagKey": "5d3ee12c4cde6a001c3e0b27",
            "tagType": 123,
            "thumb": "http://image.tmdb.org/t/p/original/lcJ8qM51ClAR2UzXU1mkZGfnn3o.jpg"
          }
        ],
        "banner": "<string>",
        "chapterSource": "media",
        "childCount": 1,
        "composite": "<string>",
        "contentRating": "<string>",
        "Country": [
          {
            "tag": "Shaun Lawton",
            "confidence": 123,
            "context": "<string>",
            "filter": "actor=49",
            "id": 123,
            "ratingKey": "58683",
            "role": "Secretary",
            "tagKey": "5d3ee12c4cde6a001c3e0b27",
            "tagType": 123,
            "thumb": "http://image.tmdb.org/t/p/original/lcJ8qM51ClAR2UzXU1mkZGfnn3o.jpg"
          }
        ],
        "Director": [
          {
            "tag": "Shaun Lawton",
            "confidence": 123,
            "context": "<string>",
            "filter": "actor=49",
            "id": 123,
            "ratingKey": "58683",
            "role": "Secretary",
            "tagKey": "5d3ee12c4cde6a001c3e0b27",
            "tagType": 123,
            "thumb": "http://image.tmdb.org/t/p/original/lcJ8qM51ClAR2UzXU1mkZGfnn3o.jpg"
          }
        ],
        "duration": 123,
        "Filter": [
          {
            "title": "<string>",
            "type": "<string>",
            "art": "<string>",
            "content": true,
            "filter": "<string>",
            "hasPrefs": true,
            "hasStoreServices": true,
            "hubKey": "<string>",
            "identifier": "<string>",
            "key": "<string>",
            "lastAccessedAt": 123,
            "Pivot": [
              {
                "title": "<string>",
                "type": "<string>",
                "context": "<string>",
                "id": "<string>",
                "key": "<string>",
                "symbol": "<string>"
              }
            ],
            "share": 123,
            "thumb": "<string>",
            "titleBar": "<string>",
            "filterType": "<string>"
          }
        ],
        "Genre": [
          {
            "tag": "Shaun Lawton",
            "confidence": 123,
            "context": "<string>",
            "filter": "actor=49",
            "id": 123,
            "ratingKey": "58683",
            "role": "Secretary",
            "tagKey": "5d3ee12c4cde6a001c3e0b27",
            "tagType": 123,
            "thumb": "http://image.tmdb.org/t/p/original/lcJ8qM51ClAR2UzXU1mkZGfnn3o.jpg"
          }
        ],
        "grandparentArt": "<string>",
        "grandparentGuid": "plex://show/5d9c081b170e24001f2a7be4",
        "grandparentHero": "<string>",
        "grandparentKey": "<string>",
        "grandparentRatingKey": "<string>",
        "grandparentTheme": "<string>",
        "grandparentThumb": "<string>",
        "grandparentTitle": "<string>",
        "guid": "plex://movie/5d7768ba96b655001fdc0408",
        "Guid": [
          {
            "id": {
              "imdbExample": {
                "summary": "IMDB example",
                "value": "imdb://tt13015952"
              },
              "tmdbExample": {
                "summary": "TMDB example",
                "value": "tmdb://2434012"
              },
              "tvdbExample": {
                "summary": "TVDB example",
                "value": "tvdb://7945991"
              }
            }
          }
        ],
        "hero": "<string>",
        "Image": [
          {
            "type": "background",
            "alt": "<string>",
            "url": "<string>"
          }
        ],
        "index": 123,
        "lastViewedAt": 1556281940,
        "leafCount": 123,
        "Media": [
          {
            "id": 1,
            "aspectRatio": 2.35,
            "audioChannels": 2,
            "audioCodec": "aac",
            "audioProfile": "lc",
            "bitrate": 5612,
            "container": "mov",
            "duration": 150192,
            "has64bitOffsets": false,
            "hasVoiceActivity": true,
            "height": 544,
            "optimizedForStreaming": false,
            "Part": [
              {
                "id": 1,
                "key": "/library/parts/1/1531779263/file.mov",
                "accessible": true,
                "audioProfile": "lc",
                "container": "mov",
                "duration": 150192,
                "exists": true,
                "file": "/home/schuyler/Videos/Trailers/Cloud Atlas (2012).mov",
                "has64bitOffsets": false,
                "indexes": "sd",
                "optimizedForStreaming": false,
                "size": 105355654,
                "Stream": [
                  {
                    "codec": "hevc",
                    "displayTitle": "4K DoVi/HDR10 (HEVC Main 10)",
                    "id": 1002625,
                    "key": "/library/streams/216389",
                    "streamType": 1,
                    "default": true,
                    "audioChannelLayout": "5.1(side)",
                    "channels": 6,
                    "bitDepth": 10,
                    "DOVIBLCompatID": 1,
                    "DOVIBLPresent": true,
                    "DOVIELPresent": false,
                    "DOVILevel": 6,
                    "DOVIPresent": true,
                    "DOVIProfile": 8,
                    "DOVIRPUPresent": true,
                    "DOVIVersion": "1.0",
                    "bitrate": 24743,
                    "canAutoSync": false,
                    "chromaLocation": "topleft",
                    "chromaSubsampling": "4:2:0",
                    "codedHeight": 1608,
                    "codedWidth": 3840,
                    "closedCaptions": true,
                    "colorPrimaries": "bt2020",
                    "colorRange": "tv",
                    "colorSpace": "bt2020nc",
                    "colorTrc": "smpte2084",
                    "extendedDisplayTitle": "4K DoVi/HDR10 (HEVC Main 10)",
                    "frameRate": 23.976,
                    "hasScalingMatrix": false,
                    "height": 1602,
                    "index": 0,
                    "language": "English",
                    "languageCode": "eng",
                    "languageTag": "en",
                    "format": "srt",
                    "headerCompression": true,
                    "level": 150,
                    "original": true,
                    "profile": "main 10",
                    "refFrames": 1,
                    "samplingRate": 48000,
                    "scanType": "progressive",
                    "embeddedInVideo": "progressive",
                    "selected": true,
                    "forced": true,
                    "hearingImpaired": true,
                    "dub": true,
                    "title": "SDH",
                    "streamIdentifier": 1,
                    "width": 3840
                  }
                ],
                "videoProfile": "main"
              }
            ],
            "videoCodec": "h264",
            "videoFrameRate": "24p",
            "videoProfile": "main",
            "videoResolution": "720",
            "width": 1280
          }
        ],
        "originallyAvailableAt": "2022-12-14",
        "originalTitle": "<string>",
        "parentGuid": "plex://show/5d9c081b170e24001f2a7be4",
        "parentHero": "<string>",
        "parentIndex": 123,
        "parentKey": "<string>",
        "parentRatingKey": "<string>",
        "parentThumb": "<string>",
        "parentTitle": "<string>",
        "primaryExtraKey": "<string>",
        "prompt": "<string>",
        "rating": 5,
        "Rating": [
          {
            "tag": "Shaun Lawton",
            "confidence": 123,
            "context": "<string>",
            "filter": "actor=49",
            "id": 123,
            "ratingKey": "58683",
            "role": "Secretary",
            "tagKey": "5d3ee12c4cde6a001c3e0b27",
            "tagType": 123,
            "thumb": "http://image.tmdb.org/t/p/original/lcJ8qM51ClAR2UzXU1mkZGfnn3o.jpg"
          }
        ],
        "ratingCount": 123,
        "ratingImage": "<string>",
        "ratingKey": "<string>",
        "Role": [
          {
            "tag": "Shaun Lawton",
            "confidence": 123,
            "context": "<string>",
            "filter": "actor=49",
            "id": 123,
            "ratingKey": "58683",
            "role": "Secretary",
            "tagKey": "5d3ee12c4cde6a001c3e0b27",
            "tagType": 123,
            "thumb": "http://image.tmdb.org/t/p/original/lcJ8qM51ClAR2UzXU1mkZGfnn3o.jpg"
          }
        ],
        "search": true,
        "secondary": true,
        "skipChildren": true,
        "skipParent": true,
        "Sort": [
          {
            "title": "<string>",
            "type": "<string>",
            "art": "<string>",
            "content": true,
            "filter": "<string>",
            "hasPrefs": true,
            "hasStoreServices": true,
            "hubKey": "<string>",
            "identifier": "<string>",
            "key": "<string>",
            "lastAccessedAt": 123,
            "Pivot": [
              {
                "title": "<string>",
                "type": "<string>",
                "context": "<string>",
                "id": "<string>",
                "key": "<string>",
                "symbol": "<string>"
              }
            ],
            "share": 123,
            "thumb": "<string>",
            "titleBar": "<string>",
            "default": "asc",
            "defaultDirection": "asc",
            "descKey": "<string>",
            "firstCharacterKey": "<string>"
          }
        ],
        "studio": "<string>",
        "subtype": "<string>",
        "summary": "<string>",
        "tagline": "<string>",
        "theme": "/library/metadata/1/theme/1705636920",
        "thumb": "/library/metadata/58683/thumb/1703239236",
        "titleSort": "<string>",
        "updatedAt": 123,
        "userRating": 5,
        "viewCount": 123,
        "viewedLeafCount": 123,
        "viewOffset": 123,
        "Writer": [
          {
            "tag": "Shaun Lawton",
            "confidence": 123,
            "context": "<string>",
            "filter": "actor=49",
            "id": 123,
            "ratingKey": "58683",
            "role": "Secretary",
            "tagKey": "5d3ee12c4cde6a001c3e0b27",
            "tagType": 123,
            "thumb": "http://image.tmdb.org/t/p/original/lcJ8qM51ClAR2UzXU1mkZGfnn3o.jpg"
          }
        ],
        "year": 123
      }
    ]
  }
}

Authorizations

​
X-Plex-Token
string
header
required

The token which identifies the user accessing the PMS. This can be either:

  • A traditional access token obtained from plex.tv
  • A JWT token obtained through the JWT authentication flow

JWT tokens provide better security with:

  • Short-lived tokens (7 days expiration)
  • Public-key cryptography (ED25519)
  • Better clock synchronization
  • Individual device revocation capability

Headers

​
accepts
enum<string>
default:application/xml

Indicates the client accepts the indicated media types

Available options:
application/json,
application/xml
​
X-Plex-Client-Identifier
string
required

An opaque identifier unique to the client

Example:

"abc123"

​
X-Plex-Product
string

The name of the client product

Example:

"Plex for Roku"

​
X-Plex-Version
string

The version of the client application

Example:

"2.4.1"

​
X-Plex-Platform
string

The platform of the client

Example:

"Roku"

​
X-Plex-Platform-Version
string

The version of the platform

Example:

"4.3 build 1057"

​
X-Plex-Device
string

A relatively friendly name for the client device

Example:

"Roku 3"

​
X-Plex-Model
string

A potentially less friendly identifier for the device model

Example:

"4200X"

​
X-Plex-Device-Vendor
string

The device vendor

Example:

"Roku"

​
X-Plex-Device-Name
string

A friendly name for the client

Example:

"Living Room TV"

​
X-Plex-Marketplace
string

The marketplace on which the client application is distributed

Example:

"googlePlay"

Query Parameters

​
type
enum<integer>

The type of media to retrieve or filter by.

1 = movie 2 = show 3 = season 4 = episode 5 = artist 6 = album 7 = track 8 = photo_album 9 = photo

E.g. A movie library will not return anything with type 3 as there are no seasons for movie libraries

Available options:
1,
2,
3,
4,
5,
6,
7,
8,
9
Example:

2

​
includeFullMetadata
enum<integer>
default:0

Whether or not to include full metadata on a positive match. When set, and the best match exceeds a score threshold of 85, metadata as rich as possible is sent back.

Available options:
0,
1
Example:

1

​
includeAncestorMetadata
enum<integer>
default:0

Whether or not to include metadata for the item's ancestor (e.g. show and season data for an episode).

Available options:
0,
1
Example:

1

​
includeAlternateMetadataSources
enum<integer>
default:0

Whether or not to return all sources for each metadata field, which results in a different structure being passed back.

Available options:
0,
1
Example:

1

​
guid
string

Used for movies, shows, artists, albums, and tracks. Allowed for various URI schemes, to be defined.

​
title
string

The title to filter by or assign

​
year
integer

Used for movies shows, and albums. Optional.

​
path
string

Used for movies, episodes, and tracks. The full path to the media file, used for "cloud-scanning" an item.

​
grandparentTitle
string

Used for episodes and tracks. The title of the show/artist. Required if path isn't passed.

​
grandparentYear
integer

Used for episodes. The year of the show.

​
parentIndex
integer

Used for episodes and tracks. The season/album number.

​
index
integer

Used for episodes and tracks. The episode/tracks number in the season/album.

​
originallyAvailableAt
string

Used for episodes. In the format YYYY-MM-DD.

​
parentTitle
string

Used for albums and tracks. The artist name for albums or the album name for tracks.

Response

200 - application/json

OK

​
MediaContainer
object

MediaContainer is the root element of most Plex API responses. It serves as a generic container for various types of content (Metadata, Hubs, Directories, etc.) and includes pagination information (offset, size, totalSize) when applicable. Common attributes: - identifier: Unique identifier for this container - size: Number of items in this response page - totalSize: Total number of items available (for pagination) - offset: Starting index of this page (for pagination) The container often "hoists" common attributes from its children. For example, if all tracks in a container share the same album title, the parentTitle attribute may appear on the MediaContainer rather than being repeated on each track.