Home 🔌 Integrations & API 📊 Keyword Rank Tracker API for NinjaCat

📊 Keyword Rank Tracker API for NinjaCat

Last updated on Oct 29, 2026

📌 What this article covers

NinjaCat and other reporting tools can pull Keyword Rank Tracker data on a schedule. That data is separate from local heatmap rankings. This article explains which data set to use, how to authenticate unattended pulls with an API key, and which filters return tracked keywords and historical daily positions.

🔍 Regular ranks versus local heatmaps

Search Atlas stores these as two different products. Do not mix their endpoints if you want standard keyword positions in NinjaCat.

  • Keyword Rank Tracker returns the keywords you track for a site or project, plus position history by day (and related fields such as URL, search engine, device, and location when those are set on the keyword).
  • Local heatmap / geo-grid rankings return map-pack style points around a business location. Those series are not a substitute for regular rank history.

If a report suddenly shows grid coordinates, many nearby pins, or local pack positions instead of one rank per tracked keyword per day, the integration is calling a heatmap endpoint. Switch it to the Keyword Rank Tracker endpoints in the in-platform API reference.

🔑 Authenticate unattended daily pulls

Server-to-server jobs, including NinjaCat scheduled imports, should authenticate with an API key. Send it on every request as the header X-API-Key. Do not rely on a browser login session for daily pulls.

  1. In Search Atlas, open your account or project API settings and create or copy an API key that can read rank data.
  2. Store the key in NinjaCat (or your scheduler) as a secret. Do not paste it into shared sheets or public dashboards.
  3. On each request, set the header X-API-Key to that key. Requests without a valid key are rejected.
  4. Use HTTPS only. Rotate the key in Search Atlas if it is exposed, then update NinjaCat.

The same header works for both Keyword Rank Tracker and heatmap calls. The header does not choose the data set. The endpoint path does.

⚙️ Endpoints and parameters to use

Exact paths and field names are listed in the API reference inside the platform and can change. Use the reference labeled for Keyword Rank Tracker, not Local Heatmap or Geo Grid. Typical read flow for a daily NinjaCat import:

  1. List tracked keywords for the site or project. Pass the site or project identifier your account uses. Optional filters often include search engine, device, location, tag, and keyword text. The response is the current tracking list (keyword id, keyword, target URL, and tracking settings).
  2. Request historical positions for those keywords. Pass the same site or project id, one or more keyword ids from step 1, and a date range (start date and end date) for the days you want. For a daily job, request yesterday through today, or a short rolling window, so you do not re-download the full history every run.
  3. Page through results when the reference shows limit, offset, page, or cursor parameters. Stop when a page is empty or the cursor is absent.

A useful daily row usually includes keyword id, keyword text, date, position (or a null/not-ranking value), ranking URL, device, and location or country. Map those columns in NinjaCat. Ignore heatmap-only fields such as grid point, latitude and longitude pin, or distance from the business centroid.

📅 How to shape the daily pull

  • Run after Search Atlas has refreshed ranks for that day. Pulling too early can omit the latest positions.
  • Keep a stable keyword id in NinjaCat so history stays attached if the keyword text is edited.
  • Request only the date window you still need. Full history is for backfill, not every night.
  • Treat a missing position as not ranked for that day. Do not copy the previous day’s rank forward unless your report design says to.
  • If the keyword list and the history call disagree, refresh the keyword list first, then pull positions for the new ids.

🛠️ If the numbers look wrong

  • Confirm the path in the API reference is Keyword Rank Tracker, not a local heatmap route.
  • Confirm X-API-Key belongs to the account that owns the project.
  • Match site or project id, device, and location to the tracker view you compare in the UI.
  • Check the date range and time zone. A one-day shift is usually a date filter, not a different endpoint.
  • Compare one keyword for one date in the product UI before remapping the whole NinjaCat model.

If you need further assistance, open the chat widget in the bottom-right corner of the platform and type human teammate to be instantly connected with a member of our team.