---
updatedAt: 2025-09-11T21:02:40.000Z
agentTools:
  projectIndex: https://developer.spyfu.com/llms.txt
---

# Find historic rankings for a domain on various keywords for a date range

Find domains historic rankings for a date range

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Ranking History API",
    "version": "v2"
  },
  "servers": [
    {
      "url": "https://api.spyfu.com/apis/organic_history_api"
    }
  ],
  "paths": {
    "/v2/historic/getHistoricRankingsForDomainOnKeywords": {
      "get": {
        "operationId": "HistoricRanking_GetHistoricRankingsForDomainOnKeywords_GET",
        "summary": "Get Domain Keyword Rankings",
        "description": "Returns historical organic ranking data for a specific domain across multiple specified keywords within a date range. Analyze how a domain's positions have changed over time for your target keyword list.\n\n[Visualize this API live on SpyFu](https://www.spyfu.com/seo/ranking-history/domain?expandChart=false&searchType=MostValuable&includeAnyTerm=true&query=example.com&sidebarContext=topics) _(TODO – verify)_",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "description": "Domain to analyze ranking history for.",
            "required": true,
            "schema": {
              "type": "string",
              "examples": [
                "example.com"
              ]
            }
          },
          {
            "name": "keywords",
            "in": "query",
            "description": "Comma-separated list of keywords to analyze rankings for.",
            "required": true,
            "schema": {
              "type": "string",
              "examples": [
                "best running shoes,nike shoes,athletic footwear"
              ]
            }
          },
          {
            "name": "startDate",
            "in": "query",
            "description": "Beginning date for range",
            "schema": {
              "type": "string",
              "format": "date-time",
              "examples": [
                "2025-01"
              ]
            },
            "example": "2025-01"
          },
          {
            "name": "endDate",
            "in": "query",
            "description": "Ending date for range",
            "schema": {
              "type": "string",
              "format": "date-time",
              "examples": [
                "2025-07"
              ]
            },
            "example": "2025-07"
          },
          {
            "name": "countryCode",
            "in": "query",
            "description": "Country to get results for.",
            "schema": {
              "type": "string",
              "examples": [
                "US"
              ],
              "default": "US",
              "enum": [
                "AR",
                "AT",
                "AU",
                "BE",
                "BR",
                "CA",
                "CH",
                "DE",
                "DK",
                "ES",
                "FR",
                "IE",
                "IN",
                "IT",
                "JP",
                "MX",
                "NL",
                "NO",
                "NZ",
                "PL",
                "PT",
                "SE",
                "SG",
                "TR",
                "UA",
                "UK",
                "US",
                "ZA"
              ],
              "x-enumDescriptions": {
                "AR": "Argentina",
                "AT": "Austria",
                "AU": "Australia",
                "BE": "Belgium",
                "BR": "Brazil",
                "CA": "Canada",
                "CH": "Switzerland",
                "DE": "Germany",
                "DK": "Denmark",
                "ES": "Spain",
                "FR": "France",
                "IE": "Ireland",
                "IN": "India",
                "IT": "Italy",
                "JP": "Japan",
                "MX": "Mexico",
                "NL": "Netherlands",
                "NO": "Norway",
                "NZ": "New Zealand",
                "PL": "Poland",
                "PT": "Portugal",
                "SE": "Sweden",
                "SG": "Singapore",
                "TR": "Turkey",
                "UA": "Ukraine",
                "UK": "United Kingdom",
                "US": "United States",
                "ZA": "South Africa"
              }
            },
            "example": "US"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved domain ranking history for specified keywords",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resultCount": {
                      "description": "Number of results returned",
                      "type": "integer",
                      "format": "int32",
                      "examples": [
                        100
                      ],
                      "readOnly": true
                    },
                    "results": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "properties": {
                          "domain": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "keyword": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "results": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "additionalProperties": {
                              "type": "integer",
                              "format": "int32"
                            }
                          }
                        },
                        "additionalProperties": false
                      }
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters, domain, or keyword list"
          },
          "401": {
            "description": "User failed authorization"
          },
          "500": {
            "description": "Server error while processing ranking history data"
          }
        },
        "tags": [
          "Ranking History API"
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "Basic_Authentication_Token": {
        "type": "http",
        "description": "<a href=\"https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side\" target=\"_blank\">Basic Authentication</a> is a standard that involves encoding your <code>SPYFU_API_ID:SECRET_KEY</code> into a Base64 string. Your <b>SpyFu API ID</b> and <b>Secret Key</b> can both be found under the <b><a href=\"https://www.spyfu.com/account/api\" target=\"_blank\">Account Settings -> API Usage</a></b> page. Additionally, you can find the Base64 string has been pre-generated on the same page under <b>Base 64 Key</b>. Finally, this encoded string is sent in the \"Authorization\" header prefixed with the keyword \"Basic\":<br>For example, to authorize as <code>00000000-0000-0000-0000-000000000000:AB12WXYZ</code> the client would send<br><pre><code>Authorization: <span class=\"token keyword\">Basic</span> <span class=\"token constructor-invocation class-name\">MDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwOkFCMTJXWFla<span></code></pre>",
        "scheme": "basic"
      },
      "Query_Parameter_Token": {
        "type": "apiKey",
        "description": "An API key can be added as a query parameter. Your API key is listed as \"Secret Key\" found under the <b><a href=\"https://www.spyfu.com/account/api\" target=\"_blank\">Account Settings -> API Usage</a></b> page<br>For example, to authorize with the API key <code>AB12WXY</code><br><pre><code>/apis/example_api/GetExample?domain=spyfu.com<span class=\"token keyword\">&api_key=AB12WXYZ</span></code></pre>",
        "name": "api_key",
        "in": "query"
      },
      "HMAC_Authentication_Header": {
        "type": "apiKey",
        "description": "For even more security, each request can be individually authenticated with a timestamped <a href=\"https://en.wikipedia.org/wiki/HMAC\" target=\"_blank\"><b>HMAC</b></a> <em>(Hash Message Authentication Code)</em> signature. Composed of your secret key, a valid timestamp, the API request path, and all request parameters. <h3>Creating the signature:</h3><br>Combine the pieces that will be converted into the signature.<br><pre><code><span class=\"token keyword\">StringToSign</span> <span class=\"token operator\">=</span><br>&#x09;HTTP-Verb <span class=\"token operator\">+</span> <span class=\"token string\">\"\\n\"</span> <span class=\"token operator\">+</span><br>&#x09;Timestamp <span class=\"token operator\">+</span> <span class=\"token string\">\"\\n\"</span> <span class=\"token operator\">+</span><br>&#x09;UrlPath <span class=\"token operator\">+</span> <span class=\"token string\">\"\\n\"</span><br>&#x09;QueryParameters<span class=\"token operator\">;</span><br></code></pre><br>Create UTF-8 encodings of the above string and of your secret key.<br><pre><code><span class=\"token keyword\">byte</span><span class=\"token operator\">[]</span> SecretKeyBytes <span class=\"token operator\">=</span> <span class=\"token function\">UTF-8-Encoding-Of</span><span class=\"token operator\">(</span> Upper-Case-Of<span class=\"token operator\">(</span> SECRET_KEY <span class=\"token operator\">)</span> <span class=\"token operator\">)</span><span class=\"token operator\">;</span><br><span class=\"token keyword\">byte</span><span class=\"token operator\">[]</span> StringToSignBytes <span class=\"token operator\">=</span> <span class=\"token function\">UTF-8-Encoding-Of</span><span class=\"token operator\">(</span> StringToSign <span class=\"token operator\">)</span><span class=\"token operator\">;</span><br></code></pre><br>Use an implementation of HMAC256 using your UTF-8 secret key to encode the combined string of your request. This should then be converted to Base64 to finish creating your signature.<br><pre><code><span class=\"token keyword\">Signature</span> <span class=\"token operator\">=</span> <span class=\"token function\">Base64</span><span class=\"token operator\">(</span> <span class=\"token function\">HMAC-SHA256</span><span class=\"token operator\">(</span> SecretKeyBytes, StringToSignBytes <span class=\"token operator\">)</span> <span class=\"token operator\">)</span><span class=\"token operator\">;</span><br></code></pre><br><h3>Using the signature:</h3><br>This signature is then sent in through an Authentication header with your username.<br><pre><code>Authentication<span class=\"token operator\">:</span> <span class=\"token keyword\">UserName</span><span class=\"token operator\">:</span><span class=\"token invocation class-name\">Signature</span></code></pre>",
        "name": "Authentication",
        "in": "header"
      }
    }
  },
  "security": [
    {
      "Basic_Authentication_Token": []
    },
    {
      "Query_Parameter_Token": []
    },
    {
      "HMAC_Authentication_Header": []
    }
  ]
}
```