API

Google Search Console API reference request examples

I found the documentation for the search console API reference to be robotic to say the least and not very welcoming.  After a bit of frustration, I got the hang of structuring the POST requests and wanted to share some of the more complicated code snippets so others can get up and running quickly.

Query example 1:

Return metrics (CTR, clicks, etc..) for individual query and page, only from the USA (note, the country code is 3 characters from ISO 3166)

{
    "startDate": "2019-01-01",
    "endDate": "2019-01-01",
    "dimensions": [
        "query",
        "page"
    ],
    "dimensionFilterGroups": [{
        "filters": [{
            "dimension": "country",
            "operator": "equals",
            "expression": "USA"
        }]
    }],
    "aggregationType": "byPage",
    "rowLimit": 1000
}

Query example 2:

Return metrics (CTR, clicks, etc..) for individual query, page and device, only from the USA and not from Mobile devices

{
  "startDate": "2019-01-01",
  "endDate": "2019-01-01",
  "dimensions": [
    "query",
    "page",
    "device"
  ],
  "dimensionFilterGroups": [
    {
      "filters": [
        {
          "dimension": "country",
          "operator": "equals",
          "expression": "USA"
        },
        {
          "dimension": "device",
          "operator": "notEquals",
          "expression": "mobile"
        }
      ]
    }
  ],
  "aggregationType": "byPage",
  "rowLimit": 1000
}

A few tips:

1) Really understand what happens when your aggregationType is by Page or by Property – see the full explanation here

Google Search ResultsMetrics Aggregated by PropertyMetrics Aggregated by Page
  1. www.petstore.example.com/monkeys
  2. www.petstore.example.com/ponies
  3. www.petstore.example.com/unicorns

Click-through rate: 100%
All clicks for a site are combined

Click-through rate: 33%
3 pages shown, 1/3 of clicks to each page

Average position: 1
Highest position from the site in the results
Average position: 2
(1 + 2 + 3) / 3 = 2

2) This API won’t parse form data, you’ll need to ensure you JSON.stringify() your object before POST and make sure you send the “Content-Type”: “application/json” header as well

David Sottimano

About David Sottimano

Trying to make OpensourceSeo.org the best free information hub for the SEO industry. Personal Website here