Google Ads keyword research

The /v1/google-ads/* routes expose Google Ads keyword planning for the Google Ads account you connect to RankParse. Use keyword-ideas to discover new keywords from seed terms or a page URL, and keyword-metrics to size a list of keywords you already have.

Before you call

Cost and daily caps

These routes cost 0 credits, so the daily caps below are the only limit on how much you can use them.

• Counting is per request, not per keyword. A keyword-metrics call with 200 keywords counts as one.
• A request is counted only after Google answers it successfully. Failed calls do not use up your cap.
• GET /v1/google-ads/accounts also calls Google and counts as one request.
• Both caps reset at midnight UTC. The 429 body includes retry_after, the number of seconds until then.
• Google enforces its own limit on top of these; hitting it returns google_ads_quota_exceeded.
• Requests are also subject to the shared 60 requests per minute rate limit (see Rate limiting).

POST /v1/google-ads/keyword-ideas

Discovers new keyword ideas from seed keywords, a URL, or both, each with average monthly searches, competition and top-of-page bid range.

Body parameters

Send JSON with Content-Type: application/json.

language and geo_target_constants are Google resource names, not bare IDs. Sending "2840" instead of "geoTargetConstants/2840" fails fast with a 400 and does not touch your cap. Google publishes the full lists of language and geo target IDs.

Example

curl -X POST "https://api.rankparse.com/v1/google-ads/keyword-ideas" \
  -H "X-API-Key: rp_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": ["seo api", "backlink checker"],
    "geo_target_constants": ["geoTargetConstants/2840"],
    "language": "languageConstants/1000",
    "limit": 25
  }'

import requests

res = requests.post(
    "https://api.rankparse.com/v1/google-ads/keyword-ideas",
    headers={"X-API-Key": "rp_your_key"},
    json={
        "keywords": ["seo api", "backlink checker"],
        "geo_target_constants": ["geoTargetConstants/2840"],
        "language": "languageConstants/1000",
        "limit": 25,
    },
)
for idea in res.json()["data"]:
    print(idea["keyword"], idea["metrics"]["avg_monthly_searches"])

const res = await fetch("https://api.rankparse.com/v1/google-ads/keyword-ideas", {
  method: "POST",
  headers: {
    "X-API-Key": "rp_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    keywords: ["seo api", "backlink checker"],
    geo_target_constants: ["geoTargetConstants/2840"],
    language: "languageConstants/1000",
    limit: 25,
  }),
});
const { data } = await res.json();

Response

{
  "data": [
    {
      "keyword": "seo api",
      "metrics": {
        "avg_monthly_searches": 1900,
        "competition": "MEDIUM",
        "competition_index": 47,
        "low_top_of_page_bid_micros": 1850000,
        "high_top_of_page_bid_micros": 6200000
      }
    }
  ],
  "total": 1,
  "total_available": 312,
  "customer_id": "1234567890"
}

Response fields

POST /v1/google-ads/keyword-metrics

Returns metrics for an explicit list of keywords, with no expansion into related terms.

Body parameters

Example

curl -X POST "https://api.rankparse.com/v1/google-ads/keyword-metrics" \
  -H "X-API-Key: rp_your_key" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["seo api", "rank tracker"]}'

import requests

res = requests.post(
    "https://api.rankparse.com/v1/google-ads/keyword-metrics",
    headers={"X-API-Key": "rp_your_key"},
    json={"keywords": ["seo api", "rank tracker"]},
)
body = res.json()
if body["truncated"]:
    print(f"Only the first {body['max_keywords']} keywords were looked up")

const res = await fetch("https://api.rankparse.com/v1/google-ads/keyword-metrics", {
  method: "POST",
  headers: {
    "X-API-Key": "rp_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ keywords: ["seo api", "rank tracker"] }),
});
const { data, truncated } = await res.json();

Response

{
  "data": [
    {
      "keyword": "seo api",
      "close_variants": ["seo apis"],
      "metrics": {
        "avg_monthly_searches": 1900,
        "competition": "MEDIUM",
        "competition_index": 47,
        "low_top_of_page_bid_micros": 1850000,
        "high_top_of_page_bid_micros": 6200000
      }
    }
  ],
  "total": 1,
  "requested": 2,
  "truncated": false,
  "max_keywords": 200,
  "customer_id": "1234567890"
}

Response fields

The metrics object

Any metric can be null when Google does not return it. A per-month volume breakdown is not included.

GET /v1/google-ads/status

Shows whether Google Ads is connected and which account is selected. It makes no call to Google, does not count against your daily cap and has no MCP tool.

{
  "connected": true,
  "google_email": "you@example.com",
  "connected_at": 1756112400000,
  "selected_customer_id": "1234567890",
  "login_customer_id": null
}

When nothing is connected the response is { "connected": false }. selected_customer_id is null while no account is chosen. login_customer_id is reserved for manager-account support and is currently always null.

GET /v1/google-ads/accounts

Lists the Google Ads accounts the connected Google login can access directly, as 10-digit customer IDs. It works before an account has been selected, and counts as one request against your daily cap.

{
  "data": ["1234567890", "9876543210"],
  "total": 2
}

An empty list means Google returned no directly accessible accounts for this login.

Errors

All errors use the standard shape { "error", "code", "message" }. See Error codes.

MCP tools

Available on the API-key MCP endpoint (mcp.rankparse.com) only, not on the secure OAuth connector. All are read-only and cost 0 credits, and every description tells the agent that results are volume and competition, not rankings. See MCP Server.

The tools accept language, geo_target_constants and keyword_plan_network like the REST routes. include_adult_keywords is accepted by get_google_ads_keyword_ideas only.

Related