---
updatedAt: 2026-08-20T21:35:28.000Z
agentTools:
  projectIndex: https://artisttools.readme.io/llms.txt
---

# Get a track's Google Rankings

Returns Google queries for which this track has been observed ranking in a supported market. Each row includes lifecycle status, current and previous position, movement, ranked URL, keyword demand, estimated traffic, and up to 30 distinct daily observations. Filters apply before the exact summary and pagination totals are calculated. Data missing or at least seven days old is refreshed automatically; if refresh fails, existing stored data is returned with freshness.stale=true, while an entity with no stored dataset returns HTTP 503. These estimates are not Google Search Console analytics.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "artist.tools V2 API",
    "description": "REST API for accessing artist.tools data about Spotify playlists, tracks, artists and curators, as well as miscellaneous utilities. All endpoints are read-only and require an `x-api-key` sent as a request header.",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://api.artist.tools/v2",
      "description": "Production server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "SEO",
      "description": "Read-only search visibility and press coverage analytics for Spotify entities. Google Rankings and Press Mentions refresh missing or stale stored data automatically; playlist Spotify Rankings use stored observations only."
    }
  ],
  "paths": {
    "/tracks/{id}/google-rankings": {
      "get": {
        "tags": [
          "SEO"
        ],
        "summary": "Get a track's Google Rankings",
        "description": "Returns Google queries for which this track has been observed ranking in a supported market. Each row includes lifecycle status, current and previous position, movement, ranked URL, keyword demand, estimated traffic, and up to 30 distinct daily observations. Filters apply before the exact summary and pagination totals are calculated. Data missing or at least seven days old is refreshed automatically; if refresh fails, existing stored data is returned with freshness.stale=true, while an entity with no stored dataset returns HTTP 503. These estimates are not Google Search Console analytics.",
        "parameters": [
          {
            "$ref": "#/components/parameters/TrackId"
          },
          {
            "$ref": "#/components/parameters/GoogleRankingQuery"
          },
          {
            "$ref": "#/components/parameters/GoogleRankingMarket"
          },
          {
            "$ref": "#/components/parameters/GoogleRankingStatus"
          },
          {
            "$ref": "#/components/parameters/GoogleRankingSortBy"
          },
          {
            "$ref": "#/components/parameters/SortDirection"
          },
          {
            "$ref": "#/components/parameters/AnalyticsPage"
          },
          {
            "$ref": "#/components/parameters/AnalyticsLimit"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/GoogleRankingsResponse"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    },
    "parameters": {
      "TrackId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "example": "1irAliF0T8sLIOPJp6n7rU"
        },
        "description": "Spotify Track ID"
      },
      "AnalyticsPage": {
        "name": "page",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 1
        },
        "description": "One-based result page. Invalid values return HTTP 400."
      },
      "AnalyticsLimit": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 25
        },
        "description": "Primary rows per page. Invalid values are rejected rather than clamped."
      },
      "SortDirection": {
        "name": "sortDirection",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "asc",
            "desc"
          ]
        },
        "description": "Sort direction. Google and playlist ranking endpoints default to asc; Press Mentions defaults to desc."
      },
      "GoogleRankingQuery": {
        "name": "q",
        "in": "query",
        "schema": {
          "type": "string",
          "maxLength": 300
        },
        "description": "Case-insensitive keyword search."
      },
      "GoogleRankingMarket": {
        "name": "market",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "au",
            "ca",
            "in",
            "nz",
            "za",
            "uk",
            "us"
          ]
        },
        "description": "Google ranking market. Omit to include every supported market."
      },
      "GoogleRankingStatus": {
        "name": "status",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "all",
            "active",
            "lost"
          ],
          "default": "all"
        },
        "description": "Lifecycle filter. active rows still rank in the latest stored dataset; lost rows no longer rank and therefore return currentPosition=null while retaining lastKnownPosition."
      },
      "GoogleRankingSortBy": {
        "name": "sortBy",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "position",
            "keyword",
            "googleVolume"
          ],
          "default": "position"
        },
        "description": "Primary sort field. position uses lastKnownPosition so active and lost rows remain sortable; stable market, keyword, and URL tie-breakers prevent rows moving unpredictably between pages."
      }
    },
    "schemas": {
      "SuccessEnvelope": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "status": {
            "type": "integer",
            "example": 200
          }
        },
        "required": [
          "success",
          "status"
        ]
      },
      "AnalyticsPagination": {
        "type": "object",
        "description": "Pagination metadata for the complete filtered result. Collection responses contain no more than 100 primary rows.",
        "properties": {
          "page": {
            "type": "integer",
            "minimum": 1,
            "description": "Current one-based page."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "Requested maximum primary rows per page."
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Exact number of rows matching all filters before pagination."
          },
          "totalPages": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of pages at the requested limit; zero when total is zero."
          },
          "hasNextPage": {
            "type": "boolean",
            "description": "Whether a later page exists."
          },
          "hasPreviousPage": {
            "type": "boolean",
            "description": "Whether an earlier non-empty page exists."
          }
        },
        "required": [
          "page",
          "limit",
          "total",
          "totalPages",
          "hasNextPage",
          "hasPreviousPage"
        ]
      },
      "AnalyticsEntity": {
        "type": "object",
        "description": "The Spotify entity whose analytics are returned.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "artist",
              "track",
              "playlist",
              "curator"
            ],
            "description": "Normalized entity type matching the endpoint resource."
          },
          "spotifyId": {
            "type": "string",
            "description": "Raw Spotify ID supplied in the request path."
          }
        },
        "required": [
          "type",
          "spotifyId"
        ]
      },
      "AnalyticsFreshness": {
        "type": "object",
        "description": "Freshness of the stored entity-level SEO dataset. Google Rankings and Press Mentions attempt an automatic refresh when data is missing or at least seven days old.",
        "properties": {
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "UTC timestamp of the stored dataset used for the response, or null when unavailable."
          },
          "stale": {
            "type": "boolean",
            "description": "True when the returned stored dataset remains at least seven days old, usually because its automatic refresh failed."
          }
        },
        "required": [
          "updatedAt",
          "stale"
        ]
      },
      "PositionObservation": {
        "type": "object",
        "description": "One distinct UTC-day ranking observation.",
        "properties": {
          "observedAt": {
            "type": "string",
            "format": "date-time",
            "description": "UTC observation timestamp."
          },
          "position": {
            "type": "integer",
            "minimum": 1,
            "description": "One-based search-result position observed at that time."
          }
        },
        "required": [
          "observedAt",
          "position"
        ]
      },
      "GoogleRanking": {
        "type": "object",
        "description": "One keyword, market, and ranked-URL combination observed for the entity.",
        "properties": {
          "keyword": {
            "type": "string",
            "description": "Google query associated with the ranking."
          },
          "market": {
            "type": "string",
            "description": "Lowercase market code in which the ranking was observed."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "lost"
            ],
            "description": "active means present in the latest stored dataset; lost means previously observed but no longer present."
          },
          "movement": {
            "type": "string",
            "enum": [
              "new",
              "rising",
              "declining",
              "unchanged"
            ],
            "nullable": true,
            "description": "Change from the previous distinct daily observation. Null for lost rows."
          },
          "currentPosition": {
            "type": "integer",
            "minimum": 1,
            "nullable": true,
            "description": "Null for lost rankings."
          },
          "previousPosition": {
            "type": "integer",
            "minimum": 1,
            "nullable": true,
            "description": "Position from the previous distinct daily observation, or null when no prior observation is available."
          },
          "lastKnownPosition": {
            "type": "integer",
            "minimum": 1,
            "description": "Most recently observed position, retained for lost rows."
          },
          "positionChange": {
            "type": "integer",
            "nullable": true,
            "description": "Positive means the ranking improved."
          },
          "rankedUrl": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "Public URL that ranked, with credentials removed; null when unavailable or invalid."
          },
          "googleVolume": {
            "type": "number",
            "minimum": 0,
            "description": "Estimated monthly Google query volume, not observed traffic to the ranked URL."
          },
          "googleDemand": {
            "type": "string",
            "enum": [
              "huge",
              "high",
              "steady",
              "low"
            ],
            "description": "Demand band derived from googleVolume: huge is 50,000+, high is 10,000-49,999, steady is 400-9,999, and low is below 400."
          },
          "estimatedMonthlyTraffic": {
            "type": "number",
            "minimum": 0,
            "description": "Modeled monthly visits attributable to this ranking; not Search Console clicks or another observed traffic count."
          },
          "firstSeenAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "UTC timestamp when this ranking was first observed, or null when unavailable."
          },
          "lastSeenAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "UTC timestamp when this ranking was most recently observed, including lost rows."
          },
          "lostAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "UTC timestamp when loss was recorded, or null for active/unknown loss time."
          },
          "history": {
            "type": "array",
            "maxItems": 30,
            "description": "At most one observation per UTC day, newest first.",
            "items": {
              "$ref": "#/components/schemas/PositionObservation"
            }
          }
        },
        "required": [
          "keyword",
          "market",
          "status",
          "movement",
          "currentPosition",
          "previousPosition",
          "lastKnownPosition",
          "positionChange",
          "rankedUrl",
          "googleVolume",
          "googleDemand",
          "estimatedMonthlyTraffic",
          "firstSeenAt",
          "lastSeenAt",
          "lostAt",
          "history"
        ]
      },
      "GoogleRankingsData": {
        "type": "object",
        "properties": {
          "entity": {
            "$ref": "#/components/schemas/AnalyticsEntity"
          },
          "freshness": {
            "$ref": "#/components/schemas/AnalyticsFreshness"
          },
          "summary": {
            "type": "object",
            "description": "Totals for the complete filtered result before pagination.",
            "properties": {
              "total": {
                "type": "integer",
                "minimum": 0
              },
              "active": {
                "type": "integer",
                "minimum": 0
              },
              "lost": {
                "type": "integer",
                "minimum": 0
              },
              "estimatedMonthlyTraffic": {
                "type": "number",
                "minimum": 0
              }
            },
            "required": [
              "total",
              "active",
              "lost",
              "estimatedMonthlyTraffic"
            ]
          },
          "rankings": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/GoogleRanking"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/AnalyticsPagination"
          }
        },
        "required": [
          "entity",
          "freshness",
          "summary",
          "rankings",
          "pagination"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          }
        },
        "required": [
          "success",
          "error",
          "status"
        ]
      }
    },
    "responses": {
      "GoogleRankingsResponse": {
        "description": "Filtered Google Rankings with exact pre-pagination summary totals.",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "google_rankings"
                      ]
                    },
                    "data": {
                      "$ref": "#/components/schemas/GoogleRankingsData"
                    }
                  },
                  "required": [
                    "type",
                    "data"
                  ]
                }
              ]
            },
            "examples": {
              "activeRanking": {
                "summary": "Active ranking with upward movement",
                "value": {
                  "success": true,
                  "status": 200,
                  "type": "google_rankings",
                  "data": {
                    "entity": {
                      "type": "playlist",
                      "spotifyId": "2SM6rniZl84fEyMCB5KMQB"
                    },
                    "freshness": {
                      "updatedAt": "2026-08-19T13:00:00.000Z",
                      "stale": false
                    },
                    "summary": {
                      "total": 1,
                      "active": 1,
                      "lost": 0,
                      "estimatedMonthlyTraffic": 420
                    },
                    "rankings": [
                      {
                        "keyword": "workout playlist 2026",
                        "market": "us",
                        "status": "active",
                        "movement": "rising",
                        "currentPosition": 4,
                        "previousPosition": 7,
                        "lastKnownPosition": 4,
                        "positionChange": 3,
                        "rankedUrl": "https://open.spotify.com/playlist/2SM6rniZl84fEyMCB5KMQB",
                        "googleVolume": 12100,
                        "googleDemand": "high",
                        "estimatedMonthlyTraffic": 420,
                        "firstSeenAt": "2026-08-01T00:00:00.000Z",
                        "lastSeenAt": "2026-08-19T13:00:00.000Z",
                        "lostAt": null,
                        "history": [
                          {
                            "observedAt": "2026-08-19T13:00:00.000Z",
                            "position": 4
                          }
                        ]
                      }
                    ],
                    "pagination": {
                      "page": 1,
                      "limit": 25,
                      "total": 1,
                      "totalPages": 1,
                      "hasNextPage": false,
                      "hasPreviousPage": false
                    }
                  }
                }
              },
              "lostRankingFromStaleFallback": {
                "summary": "Lost ranking returned from a stale stored dataset",
                "value": {
                  "success": true,
                  "status": 200,
                  "type": "google_rankings",
                  "data": {
                    "entity": {
                      "type": "playlist",
                      "spotifyId": "2SM6rniZl84fEyMCB5KMQB"
                    },
                    "freshness": {
                      "updatedAt": "2026-07-30T13:00:00.000Z",
                      "stale": true
                    },
                    "summary": {
                      "total": 1,
                      "active": 0,
                      "lost": 1,
                      "estimatedMonthlyTraffic": 0
                    },
                    "rankings": [
                      {
                        "keyword": "gym music",
                        "market": "us",
                        "status": "lost",
                        "movement": null,
                        "currentPosition": null,
                        "previousPosition": 12,
                        "lastKnownPosition": 9,
                        "positionChange": null,
                        "rankedUrl": "https://open.spotify.com/playlist/2SM6rniZl84fEyMCB5KMQB",
                        "googleVolume": 9900,
                        "googleDemand": "steady",
                        "estimatedMonthlyTraffic": 0,
                        "firstSeenAt": "2026-06-10T00:00:00.000Z",
                        "lastSeenAt": "2026-07-21T00:00:00.000Z",
                        "lostAt": "2026-07-30T13:00:00.000Z",
                        "history": [
                          {
                            "observedAt": "2026-07-21T00:00:00.000Z",
                            "position": 9
                          }
                        ]
                      }
                    ],
                    "pagination": {
                      "page": 1,
                      "limit": 25,
                      "total": 1,
                      "totalPages": 1,
                      "hasNextPage": false,
                      "hasPreviousPage": false
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "No stored dataset was available and an automatic SEO refresh failed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "BadRequest": {
        "description": "Client error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  }
}
```