# SEO Tools API

> Create a key and run SEO Tools reports through the API.

Canonical: https://docs.georanker.com/docs/seo-tools-api

Use the SEO Tools API to create reports, retrieve results as JSON, and bring GeoRanker data into your own dashboards and workflows. A project, called a campaign in SEO Tools, groups reports and saved keyword lists.

## API keys and authentication

* [Create an API key and make your first request](https://docs.georanker.com/docs/seo-tools-api-quickstart). Follow the illustrated setup in the GeoRanker Platform and test the key by listing projects.

## Projects and keyword lists

* [Work with projects, dashboard data, and keyword lists](https://docs.georanker.com/docs/seo-tools-api-projects-and-lists). Find a project ID, read dashboard activity, and save lists of terms.

## Report guides

| Report                                                   | Use it to                                                | What you get                                                                                   |
| -------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| [Rank Tracker](https://docs.georanker.com/docs/seo-tools-api-rank-tracker)         | Track how a domain's search positions change.            | Keyword rankings across selected engines, locations and devices, with optional recurring runs. |
| [SERP Snapshot](https://docs.georanker.com/docs/seo-tools-api-serp-snapshot)       | Inspect what appeared for a search in a specific market. | A point-in-time set of search results by keyword and search context.                           |
| [Heatmap](https://docs.georanker.com/docs/seo-tools-api-heatmap)                   | Compare which competitors rank across markets.           | Search positions side by side across locations. The app calls this SEO Competitors.            |
| [Local Map Rank](https://docs.georanker.com/docs/seo-tools-api-local-map-rank)     | Measure how rankings change within a local area.         | A grid of coordinates and rankings for the target, with competitor results where available.    |
| [OnPage](https://docs.georanker.com/docs/seo-tools-api-onpage)                     | Audit a page for performance and SEO issues.             | Lighthouse and PageSpeed Insights audit data for the selected URL and device.                  |
| [Broken Links](https://docs.georanker.com/docs/seo-tools-api-broken-links)         | Find broken links and the pages that contain them.       | Crawl totals and link issues you can trace back to their source pages.                         |
| [Backlinks](https://docs.georanker.com/docs/seo-tools-api-backlinks)               | Find sites that link to a domain or page.                | Backlink data grouped by the selected report mode.                                             |
| [Keyword Research](https://docs.georanker.com/docs/seo-tools-api-keyword-research) | Find and prioritize terms to investigate.                | Keyword research rows based on your seeds, market, and report mode.                            |

## How to run a report

* List your projects with `GET /api/projects` and save the UUID of the campaign you want to use.
* Follow the creation example for your report type. Some endpoints expect the inputs inside `payload`. Local Map Rank uses `campaignId`, and Keyword Research takes the project ID in the URL.
* Save the report ID returned by the create call. A successful create response can arrive before the data is ready.
* Poll the endpoint shown in the report guide, leaving a delay between requests. Heatmap exposes a `pending` count in its results. Local Map Rank exposes `report.status` in its detail response. Stop polling on completion, failure, or your integration's timeout.
* Fetch the data using the report's result endpoint. Local Map Rank, OnPage, Broken Links, Backlinks, and Keyword Research return results through the detail endpoint. Rank Tracker, SERP Snapshot, and Heatmap provide separate result routes.
* Store the report ID alongside the project ID and the inputs you submitted. If a create request times out, check the project report list before submitting again to avoid duplicate runs.

## Share results

* [Share a supported report](https://docs.georanker.com/docs/seo-tools-api-sharing). Create or revoke access and retrieve results with a share token.

## API reference

The API origin is `https://seoapi.georanker.com`. Use the interactive reference for request schemas and HTTP responses. [SEO Tools API reference](https://seoapi.georanker.com/api/docs)
