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
| 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.
| 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.
| 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.
| 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.
| 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:
| 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.
| 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.
| 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