GeoRanker Docs
SEO Tools APIReport guides

Keyword Research

Compare keyword demand, discover ideas, and read forecasts.

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.

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.

{
  "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

Choose a different research question

Research questionProvider and endpoint used by the appResult
Find related keyword ideasgoogle_ads with keywords_for_keywordsKeyword suggestions from seed terms, with demand and advertising metrics where available.
Find keywords related to a sitegoogle_ads with keywords_for_siteIdeas for a domain or page. The app asks for a target URL.
Estimate paid search trafficgoogle_ads with ad_traffic_by_keywordsForecast impressions, clicks and cost per click. The app asks for a bid.
Measure demand on Bingbing with search_volumeSearch-volume results for the selected market.
Track relative search interestgoogle_trends with exploreTrend 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. Keyword Research API reference

SEO Tools API overview