Search for Match

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

NameDescription
ip_addressThe IP address of the Plex Media server.
plex_tokenThe Plex token.
idThe 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 CodeDescription
200Success - The request was successful.
401Unauthorized - The Plex token provided was not valid.
403Forbidden - 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
AttributeDescription
sizeThe number of media items.
identifierThe type of item.
mediaTagPrefixPrefix for the media tag.
mediaTagVersionMedia 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
AttributeDescription
thumbThe thumbnail for the movie.
typeThe type of item represented by this SearchResult element.
guidThe unique identifier for the movie.
nameThe name of the movie.
yearThe year the movie was released.
summaryInformation about the movie.
lifespanEndedThe 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
AttributeDescription
thumbThe thumbnail for the tv show series.
typeThe type of item represented by this SearchResult element.
guidThe unique identifier for the tv show series.
nameThe name of the tv show series.
yearThe year the tv show series was released.
summaryInformation about the tv show series.
lifespanEndedThe 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
AttributeDescription
thumbThe thumbnail for the tv show season.
typeThe type of item represented by this SearchResult element.
guidThe unique identifier for the tv show season.
nameThe name of the tv show season.
parentNameThe name of the TV show series.
parentGUIDN/A
yearThe year the tv show season was released.
summaryInformation about the tv show season.
lifespanEndedThe 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
AttributeDescription
thumbThe thumbnail for the music artist.
typeThe type of item represented by this SearchResult element.
guidThe unique identifier for the music artist.
nameThe name of the music artist.
scoreThe accuracy of the match. 100 is a perfect match.
disambiguationA brief description of the music artist.
beginAreaLocation where the music artist started.
areaLocation of the music artist.
lifespanBeginThe date the music artist started.
lifespanEndedThe 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
AttributeDescription
thumbThe thumbnail for the music album.
typeThe type of item represented by this SearchResult element.
guidThe unique identifier for the music album.
nameThe name of the music album.
parentNameThe name of the music artist.
parentGUIDN/A
scoreThe accuracy of the match. 100 is a perfect match.
yearThe year the music album was released.
lifespanEndedThe 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
AttributeDescription
idThe identifier of the music track.
typeThe type of item represented by this SearchResult element.
indexThe order of the music track.
guidThe unique identifier for the music track.
nameThe name of the music track.
matchedThe music track was matched with a media file successfully.
lifespanEndedThe 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
Subscribe
Display