Search for Match

Buy me a coffee

When Plex scans the media files to download the metadata, it searches online for a match. When it finds a match it downloads and displays the metadata.

Sometimes it may not be able to find a match or find an incorrect match. In that situation, you can use the Match or Fix Match options in Plex to manually match the items.

This API command will have Plex return all the matches it finds for a specific media item.

URL

GET http://{ip_address}:32400/library/metadata/{id}/matches?manual=1&X-Plex-Token={plex_token}

Parameters

Name	Description
ip_address	The IP address of the Plex Media server.
plex_token	The Plex token.
id	The key associated with a media item on the Plex server. This key can be found from the Plex Web App and hovering over the media item and looking for number in the `key` parameter of the URL.

Return Status

HTTP Code	Description
200	Success - The request was successful.
401	Unauthorized - The Plex token provided was not valid.
403	Forbidden - TheID for the media item was not valid.

Response

XML string value that returns a list of all the search results for the specified media ID. An example of the XML returned from the request is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<MediaContainer size="15" identifier="com.plexapp.plugins.library" mediaTagPrefix="/system/bundle/media/flags/" mediaTagVersion="1682076900">
<SearchResult thumb="https://images.plex.tv/photo?height=336&width=225&minSize=1&upscale=1&url=https%3A%2F%2Fmetadata-static%2Eplex%2Etv%2F2%2Fgracenote%2F2e4e8322b279380ce4f0fe45706afd56%2Ejpg" type="movie" guid="plex://movie/5d776840999c64001ec317ab" name="Persuasion" year="1995" summary="Anne Elliot, the daughter of a financially troubled aristocratic family, is persuaded to break her engagement to Frederick Wentworth, a young sea captain of meager means. Years later, money troubles force Anne's father to rent out the family estate to Admiral Croft, and Anne is again thrown into company with Frederick -- who is now rich, successful, and perhaps still in love with Anne." lifespanEnded="0"></SearchResult>
<SearchResult thumb="https://images.plex.tv/photo?height=336&width=225&minSize=1&upscale=1&url=https%3A%2F%2Fm%2Emedia-amazon%2Ecom%2Fimages%2FM%2FMV5BNDI5YWM5YTMtYmY4Zi00OWU0LTg3MjQtZDY3MjlmNTg1NWQ1XkEyXkFqcGdeQXVyMDcxODUzNw%40%40%2E_V1_%2Ejpg" type="movie" guid="plex://movie/62f6918557587a76f9549b4d" name="Jane Austen's Persuasion" summary="Theatrical film of Persuasion with Ciaran Hinds & Amanda Root. Directed by Roger Michell." lifespanEnded="0"></SearchResult>
<SearchResult thumb="https://images.plex.tv/photo?height=336&width=225&minSize=1&upscale=1&url=https%3A%2F%2Fm%2Emedia-amazon%2Ecom%2Fimages%2FM%2FMV5BYTdhMmEyOGYtZGQyNS00NTZlLWExYTgtZTdlYTIwMmZlYzk2XkEyXkFqcGdeQXVyNjY2MTYyMg%40%40%2E_V1_%2Ejpg" type="movie" guid="plex://movie/6242c10be358a5a82815e85f" name="Persuasion" year="1995" summary="A young spinster Englishwoman and the now-successful Navy Captain she was "persuaded" to refuse seven years earlier meet again, while experiencing a reversal of fortunes." lifespanEnded="0"></SearchResult>
    ...
</MediaContainer>

The XML returned provides a brief of the search results for the media item. The search results returned will have fields specific to the tpe of media that was searched.

MediaContainer Attributes
Attribute	Description
size	The number of media items.
identifier	The type of item.
mediaTagPrefix	Prefix for the media tag.
mediaTagVersion	Media tag version. Note: This could be a date and time value.

Movies

Within the MediaContainer there are one or more SearchResult child elements. Each SearchResult element represents one movie result for the media item.

Search Result Attributes
Attribute	Description
thumb	The thumbnail for the movie.
type	The type of item represented by this `SearchResult` element.
guid	The unique identifier for the movie.
name	The name of the movie.
year	The year the movie was released.
summary	Information about the movie.
lifespanEnded	The date the movie ended. 0 for no date

TV Show Series

Each TV show series will return one or more SearchResult element.

Search Result Attributes
Attribute	Description
thumb	The thumbnail for the tv show series.
type	The type of item represented by this `SearchResult` element.
guid	The unique identifier for the tv show series.
name	The name of the tv show series.
year	The year the tv show series was released.
summary	Information about the tv show series.
lifespanEnded	The date the tv show series ended. 0 for no date

TV Show Season

A TV show series will also have one or more seasons. If the TV show series matches, then there shouldn't be too much issue with the seasons. A SearchResult element would also be returned for a season, although there will usually be only one returned.

Search Result Attributes
Attribute	Description
thumb	The thumbnail for the tv show season.
type	The type of item represented by this `SearchResult` element.
guid	The unique identifier for the tv show season.
name	The name of the tv show season.
parentName	The name of the TV show series.
parentGUID	N/A
year	The year the tv show season was released.
summary	Information about the tv show season.
lifespanEnded	The date the tv show season ended. 0 for no date

Music Artist

There could multiple SearchResult elements returned when search for a music artist. EAch SearchResult will have the following attributes:

Search Result Attributes
Attribute	Description
thumb	The thumbnail for the music artist.
type	The type of item represented by this `SearchResult` element.
guid	The unique identifier for the music artist.
name	The name of the music artist.
score	The accuracy of the match. 100 is a perfect match.
disambiguation	A brief description of the music artist.
beginArea	Location where the music artist started.
area	Location of the music artist.
lifespanBegin	The date the music artist started.
lifespanEnded	The date the music artist ended. 0 for no date

Music Album

The album for an artist can produce multiple SearchResult elements. Within each of the SearchResult elements could be a child SearchResult element for each track of the album.

Search Result Attributes
Attribute	Description
thumb	The thumbnail for the music album.
type	The type of item represented by this `SearchResult` element.
guid	The unique identifier for the music album.
name	The name of the music album.
parentName	The name of the music artist.
parentGUID	N/A
score	The accuracy of the match. 100 is a perfect match.
year	The year the music album was released.
lifespanEnded	The date the music album ended. 0 for no date

Music Album Track

This is the only SearchResult child element. Each SearchResult element represents one track of an album.

Search Result Attributes
Attribute	Description
id	The identifier of the music track.
type	The type of item represented by this `SearchResult` element.
index	The order of the music track.
guid	The unique identifier for the music track.
name	The name of the music track.
matched	The music track was matched with a media file successfully.
lifespanEnded	The date the music track ended. 0 for no date

Examples

curl -X GET http://{ip_address}:32400/library/metadata/{id}/matches?manual=1&X-Plex-Token={plex_token}

import requests
plex_url = http://{ip_address}:32400/library/metadata/{id}/matches?manual=1&X-Plex-Token={plex_token}
response = requests.get(plex_url)
print(response.text)

$response = Invoke-RestMethod 'http://{ip_address}:32400/library/metadata/{id}/matches?manual=1&X-Plex-Token={plex_token}' -Method 'GET'
Write-Output $response

Buy me a coffee