# Keyword Research

> Compare keyword demand, discover ideas, and read forecasts.

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

Run Keyword Research to compare demand for specific search terms or get related ideas from a seed list. The example below requests Google Ads search volume for two terms. Reports belong to a project and return a `reportId` you can use to fetch the results.

## Run a search-volume report

Set `SEO_TOOLS_API_KEY` to your API key and `PROJECT_ID` to the UUID of an accessible project from `GET /api/projects`. This example uses curl and jq.

```bash
API='https://seoapi.georanker.com'
KEYWORD_REPORT_ID=$(curl --fail-with-body -sS \
  "$API/api/projects/$PROJECT_ID/keywords/run" \
  -H "Authorization: Bearer $SEO_TOOLS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "US hotel keyword demand",
    "provider": "google_ads",
    "endpoint": "search_volume",
    "keywords": ["hotels in New York", "hotels in Chicago"],
    "location": "United States"
  }' | jq -er '.reportId')

curl --fail-with-body -sS "$API/api/keywords/$KEYWORD_REPORT_ID" \
  -H "Authorization: Bearer $SEO_TOOLS_API_KEY" | jq .
```

The public request schema requires `name`, `provider`, `endpoint` and a string array called `keywords`. It lists `location` as optional. The signed-in form uses `reportName` and `locationName` for its own requests. The public schema leaves the available provider and endpoint combinations open. The `google_ads` and `search_volume` identifiers above are used by the SEO Tools app.

The POST returns HTTP 201 with the queued report's `reportId`. To find earlier runs, call `GET /api/projects/{projectId}/keyword-reports`. Pass the `mine=true` query parameter to filter the list to your reports. Each list record can include the report ID, name, provider, endpoint, location and processing flags.

## Read keyword demand and advertising metrics

The detail endpoint returns a JSON object. The viewer reads keyword rows from `data` and refreshes while both `providerCalled` and `hasError` are false. Check for an error before importing rows. The public schema leaves the provider-specific row fields unspecified.

This shortened example uses illustrative values for a Google Ads volume report.

```json
{
  "providerCalled": true,
  "hasError": false,
  "data": [
    {
      "keyword": "hotels in New York",
      "search_volume": 74000,
      "competition": "HIGH",
      "competition_index": 89,
      "cpc": 2.8,
      "monthly_searches": [
        { "year": 2026, "month": 9, "search_volume": 60500 }
      ]
    }
  ]
}
```

The viewer takes the most recent entry in `monthly_searches` for the displayed Search Volume, which is 60,500 in the example. When monthly data is absent, it uses the row's `search_volume`. Keep the year and month when exporting historical values. Competition measures advertiser competition, and the viewer displays cost per click in USD. When present, `low_top_of_page_bid` and `high_top_of_page_bid` give additional context for bid comparisons. [Read a search-volume report](https://docs.georanker.com/docs/keyword-volumes)

## Choose a different research question

| Research question               | Provider and endpoint used by the app      | Result                                                                                    |
| ------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------- |
| Find related keyword ideas      | `google_ads` with `keywords_for_keywords`  | Keyword suggestions from seed terms, with demand and advertising metrics where available. |
| Find keywords related to a site | `google_ads` with `keywords_for_site`      | Ideas for a domain or page. The app asks for a target URL.                                |
| Estimate paid search traffic    | `google_ads` with `ad_traffic_by_keywords` | Forecast impressions, clicks and cost per click. The app asks for a bid.                  |
| Measure demand on Bing          | `bing` with `search_volume`                | Search-volume results for the selected market.                                            |
| Track relative search interest  | `google_trends` with `explore`             | Trend results for the selected terms, period and output options.                          |

The public create schema documents the shared keyword-array request. Mode-specific settings such as the target URL, bid and Trends output selection are available in the signed-in form. [Explore keyword ideas](https://docs.georanker.com/docs/keyword-suggestions-1). [Keyword Research API reference](https://seoapi.georanker.com/api/docs#/Keywords)

[SEO Tools API overview](https://docs.georanker.com/docs/seo-tools-api)
