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 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. Keyword Research API reference