> Markdown versions of all pages of this connector library are available by appending `.md` to the page URL. For the full index of connectors, see [llms.txt](https://connectors.appmixer.com/llms.txt).

# Find Tracks

- Component: `appmixer.spotify.core.FindTracks`
- Kind: Action
- Version: 1.0.0
- Visibility: Public
- Connector: [appmixer.spotify 1.0.0](https://connectors.appmixer.com/connector/appmixer.spotify/1.0.0.md)
- Component page: <https://connectors.appmixer.com/connector/appmixer.spotify/1.0.0/component/appmixer.spotify.core.FindTracks>

Search the Spotify catalogue for tracks and score how well each result matches the requested artist and title. Built for hand-typed tracklists: typos, "ft"/"+" collaborators and "/four tet rmx" version suffixes still match. Results below the minimum score leave through the Not Found port.

## Input ports

### Port `in`

| Field | Type | Description |
| --- | --- | --- |
| Artist (`artist`) | text | The performing artist, as written in your source. Collaborators may be separated by `ft`, `feat.`, `&`, `+`, `,` or `x` - only the first one is matched. Fill Artist and Title together to get match scoring. |
| Title (`title`) | text | The song title. A version suffix such as `/four tet rmx`, `(Radio Edit)` or `- Live` is understood and matched separately from the song itself. |
| Search Query (`query`) | text | Free-text search, used when Artist and Title are not both filled in. With free text the score compares the whole query against the candidate, so the structured fields give better matches. |
| Minimum Match Score (`minScore`) | number | Between 0 and 1. Results scoring below this are dropped; when nothing is left, the input is emitted on the Not Found port. 0.75 accepts a typo or two, 0.9 is close to exact. |
| Maximum Results (`maxResults`) | number | How many candidates to score, 1 to 50. Spotify serves 10 per page, so 50 costs five API calls against the rolling rate-limit window. |
| Market (`market`) | text | Optional ISO 3166-1 alpha-2 country code (e.g. `CZ`) to restrict results to tracks available in that market. |
| Output Type (`outputType`) | select | Choose whether you want to receive the result set as one complete list, first item only, one item at a time, or stream the items to a file. Building a playlist from a tracklist usually wants "First Item Only" - the best-scoring match. |

## Output ports

### Port `out`

Variables are loaded dynamically from `/component/appmixer/spotify/core/FindTracks?outPort=out&ignoreAuth=true`.

### Port `notFound`

| Field | Type | Description |
| --- | --- | --- |
| Search Query (`query`) | string | - |
| Artist (`artist`) | string | - |
| Title (`title`) | string | - |
| Minimum Match Score (`minScore`) | number | - |
| Candidates Scored (`candidates`) | integer | - |

## Full metadata (component.json)

```json
{
  "name": "appmixer.spotify.core.FindTracks",
  "label": "Find Tracks",
  "description": "Search the Spotify catalogue for tracks and score how well each result matches the requested artist and title. Built for hand-typed tracklists: typos, \"ft\"/\"+\" collaborators and \"/four tet rmx\" version suffixes still match. Results below the minimum score leave through the Not Found port.",
  "author": "Appmixer <info@appmixer.com>",
  "version": "1.0.0",
  "auth": {
    "service": "appmixer:spotify"
  },
  "quota": {
    "manager": "appmixer:spotify",
    "resources": "requests",
    "scope": {
      "userId": "{{userId}}"
    }
  },
  "inPorts": [
    {
      "name": "in",
      "schema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "artist": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "minScore": {
            "type": "number"
          },
          "maxResults": {
            "type": "integer"
          },
          "market": {
            "type": "string"
          },
          "outputType": {
            "type": "string"
          }
        }
      },
      "inspector": {
        "inputs": {
          "artist": {
            "type": "text",
            "index": 1,
            "label": "Artist",
            "tooltip": "The performing artist, as written in your source. Collaborators may be separated by <code>ft</code>, <code>feat.</code>, <code>&amp;</code>, <code>+</code>, <code>,</code> or <code>x</code> - only the first one is matched. Fill Artist and Title together to get match scoring."
          },
          "title": {
            "type": "text",
            "index": 2,
            "label": "Title",
            "tooltip": "The song title. A version suffix such as <code>/four tet rmx</code>, <code>(Radio Edit)</code> or <code>- Live</code> is understood and matched separately from the song itself."
          },
          "query": {
            "type": "text",
            "index": 3,
            "label": "Search Query",
            "tooltip": "Free-text search, used when Artist and Title are not both filled in. With free text the score compares the whole query against the candidate, so the structured fields give better matches."
          },
          "minScore": {
            "type": "number",
            "index": 4,
            "label": "Minimum Match Score",
            "defaultValue": 0.75,
            "tooltip": "Between 0 and 1. Results scoring below this are dropped; when nothing is left, the input is emitted on the Not Found port. 0.75 accepts a typo or two, 0.9 is close to exact."
          },
          "maxResults": {
            "type": "number",
            "index": 5,
            "label": "Maximum Results",
            "defaultValue": 10,
            "tooltip": "How many candidates to score, 1 to 50. Spotify serves 10 per page, so 50 costs five API calls against the rolling rate-limit window."
          },
          "market": {
            "type": "text",
            "index": 6,
            "label": "Market",
            "tooltip": "Optional ISO 3166-1 alpha-2 country code (e.g. <code>CZ</code>) to restrict results to tracks available in that market."
          },
          "outputType": {
            "type": "select",
            "index": 7,
            "label": "Output Type",
            "defaultValue": "first",
            "tooltip": "Choose whether you want to receive the result set as one complete list, first item only, one item at a time, or stream the items to a file. Building a playlist from a tracklist usually wants \"First Item Only\" - the best-scoring match.",
            "options": [
              {
                "label": "First Item Only",
                "value": "first"
              },
              {
                "label": "All items at once",
                "value": "array"
              },
              {
                "label": "One item at a time",
                "value": "object"
              },
              {
                "label": "Store to CSV file",
                "value": "file"
              }
            ]
          }
        }
      }
    }
  ],
  "outPorts": [
    {
      "name": "out",
      "source": {
        "url": "/component/appmixer/spotify/core/FindTracks?outPort=out&ignoreAuth=true",
        "data": {
          "properties": {
            "generateOutputPortOptions": true
          },
          "messages": {
            "in/outputType": "inputs/in/outputType"
          }
        }
      }
    },
    {
      "name": "notFound",
      "schema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "title": "Search Query",
            "example": "calibre low hangong"
          },
          "artist": {
            "type": "string",
            "title": "Artist",
            "example": "calibre"
          },
          "title": {
            "type": "string",
            "title": "Title",
            "example": "low hangong"
          },
          "minScore": {
            "type": "number",
            "title": "Minimum Match Score",
            "example": 0.75
          },
          "candidates": {
            "type": "integer",
            "title": "Candidates Scored",
            "example": 10
          }
        }
      }
    }
  ],
  "icon": "(data URI omitted)"
}
```
