openapi: 3.1.0
info:
title: Google Search Console API
description: >-
The Google Search Console API provides programmatic access to Search Console
data. Query search analytics to understand how your site appears in Google
Search results, manage sitemaps for efficient crawling, inspect individual
URLs to check indexing status and crawl details, and manage site-level
verification and permissions.
version: v1
contact:
name: Google Search Console API Support
url: https://support.google.com/webmasters/
termsOfService: https://developers.google.com/terms
license:
name: Creative Commons Attribution 4.0
url: https://creativecommons.org/licenses/by/4.0/
externalDocs:
description: Google Search Console API Documentation
url: https://developers.google.com/webmaster-tools/v1/api_reference_index
servers:
- url: https://searchconsole.googleapis.com
description: Google Search Console API Production Server
tags:
- name: Search Analytics
description: >-
Query search traffic data for your site. Retrieve impressions, clicks,
click-through rate, and average position grouped by dimensions such as
query, page, country, device, search type, and date.
- name: Sitemaps
description: >-
Submit and manage sitemaps and sitemap indexes for your site. List
submitted sitemaps, check their processing status, submit new sitemaps,
and delete previously submitted sitemaps.
- name: Sites
description: >-
Manage site-level access and verification. List verified sites, get
details about a specific site, add new sites, and remove sites from
your Search Console account.
- name: URL Inspection
description: >-
Inspect individual URLs to retrieve detailed indexing, crawling, and
serving information. Check whether a URL is indexed, view crawl details,
mobile usability status, and rich results eligibility.
security:
- OAuth2:
- https://www.googleapis.com/auth/webmasters
paths:
/webmasters/v3/sites:
get:
operationId: listSites
summary: Google Search Console List Sites
description: >-
Lists the user's Search Console sites. Returns all sites that the
authenticated user has been verified for or has been granted access to
through delegation.
tags:
- Sites
security:
- OAuth2:
- https://www.googleapis.com/auth/webmasters.readonly
responses:
'200':
description: List of Search Console sites.
content:
application/json:
schema:
$ref: '#/components/schemas/SitesListResponse'
examples:
Listsites200Example:
summary: Default listSites 200 response
x-microcks-default: true
value:
siteEntry:
- siteUrl: https://www.example.com
permissionLevel: siteOwner
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/webmasters/v3/sites/{siteUrl}:
get:
operationId: getSite
summary: Google Search Console Get Site Details
description: >-
Retrieves information about a specific site, including its permission
level for the authenticated user.
tags:
- Sites
security:
- OAuth2:
- https://www.googleapis.com/auth/webmasters.readonly
parameters:
- $ref: '#/components/parameters/SiteUrl'
responses:
'200':
description: Site details.
content:
application/json:
schema:
$ref: '#/components/schemas/WmxSite'
examples:
Getsite200Example:
summary: Default getSite 200 response
x-microcks-default: true
value:
siteUrl: https://www.example.com
permissionLevel: siteOwner
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: addSite
summary: Google Search Console Add a Site
description: >-
Adds a site to the set of the user's Search Console sites. The site
URL must be a valid property URL. After adding, the site must still
be verified before full data access is granted.
tags:
- Sites
parameters:
- $ref: '#/components/parameters/SiteUrl'
responses:
'204':
description: Site added successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteSite
summary: Google Search Console Remove a Site
description: >-
Removes a site from the set of the user's Search Console sites.
This does not delete any data associated with the site.
tags:
- Sites
parameters:
- $ref: '#/components/parameters/SiteUrl'
responses:
'204':
description: Site removed successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/webmasters/v3/sites/{siteUrl}/searchAnalytics/query:
post:
operationId: querySearchAnalytics
summary: Google Search Console Query Search Analytics
description: >-
Query your search traffic data with filters and parameters that you
define. Returns zero or more rows grouped by the row keys (dimensions)
that you define. You must define a date range of one or more days.
When date is one of the dimensions, any days without data are omitted
from the result list. Data is available starting from the date the
site was added to Search Console, and there is a processing delay of
approximately 2-3 days.
tags:
- Search Analytics
parameters:
- $ref: '#/components/parameters/SiteUrl'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchAnalyticsQueryRequest'
example:
startDate: '2025-01-01'
endDate: '2025-01-31'
dimensions:
- query
- page
type: web
rowLimit: 10
startRow: 0
responses:
'200':
description: Search analytics query results.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchAnalyticsQueryResponse'
examples:
Querysearchanalytics200Example:
summary: Default querySearchAnalytics 200 response
x-microcks-default: true
value:
rows:
- keys: {}
clicks: 42.5
impressions: 42.5
ctr: 42.5
position: 42.5
responseAggregationType: auto
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/webmasters/v3/sites/{siteUrl}/sitemaps:
get:
operationId: listSitemaps
summary: Google Search Console List Sitemaps
description: >-
Lists the sitemaps submitted for the specified site. Returns both
manually submitted sitemaps and sitemaps discovered via robots.txt.
Includes processing status, error counts, and content details for
each sitemap.
tags:
- Sitemaps
security:
- OAuth2:
- https://www.googleapis.com/auth/webmasters.readonly
parameters:
- $ref: '#/components/parameters/SiteUrl'
- name: sitemapIndex
in: query
required: false
description: >-
A URL of a sitemap index. If specified, only sitemaps that are
listed in this sitemap index are returned.
schema:
type: string
format: uri
example: https://www.example.com
responses:
'200':
description: List of sitemaps.
content:
application/json:
schema:
$ref: '#/components/schemas/SitemapsListResponse'
examples:
Listsitemaps200Example:
summary: Default listSitemaps 200 response
x-microcks-default: true
value:
sitemap:
- path: https://www.example.com
lastSubmitted: '2026-01-15T10:30:00Z'
isPending: true
isSitemapsIndex: true
type: atomFeed
lastDownloaded: '2026-01-15T10:30:00Z'
warnings: 10
errors: 10
contents: {}
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath}:
get:
operationId: getSitemap
summary: Google Search Console Get Sitemap Details
description: >-
Retrieves information about a specific sitemap, including its type,
last submission time, processing status, warnings, errors, and the
number of URLs it contains.
tags:
- Sitemaps
security:
- OAuth2:
- https://www.googleapis.com/auth/webmasters.readonly
parameters:
- $ref: '#/components/parameters/SiteUrl'
- $ref: '#/components/parameters/Feedpath'
responses:
'200':
description: Sitemap details.
content:
application/json:
schema:
$ref: '#/components/schemas/WmxSitemap'
examples:
Getsitemap200Example:
summary: Default getSitemap 200 response
x-microcks-default: true
value:
path: https://www.example.com
lastSubmitted: '2026-01-15T10:30:00Z'
isPending: true
isSitemapsIndex: true
type: atomFeed
lastDownloaded: '2026-01-15T10:30:00Z'
warnings: 10
errors: 10
contents:
- type: web
submitted: 10
indexed: 10
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: submitSitemap
summary: Google Search Console Submit a Sitemap
description: >-
Submits a sitemap for a site. If the sitemap has already been submitted,
it will be resubmitted and re-processed. The sitemap URL must be
accessible to Googlebot. Submitting a sitemap index will submit all
sitemaps listed in the index.
tags:
- Sitemaps
parameters:
- $ref: '#/components/parameters/SiteUrl'
- $ref: '#/components/parameters/Feedpath'
responses:
'204':
description: Sitemap submitted successfully.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteSitemap
summary: Google Search Console Delete a Sitemap
description: >-
Deletes a previously submitted sitemap from Search Console. This
does not prevent Google from crawling the URLs in the sitemap; it
only removes the sitemap from the list of submitted sitemaps in
Search Console.
tags:
- Sitemaps
parameters:
- $ref: '#/components/parameters/SiteUrl'
- $ref: '#/components/parameters/Feedpath'
responses:
'204':
description: Sitemap deleted successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v1/urlInspection/index:inspect:
post:
operationId: inspectUrl
summary: Google Search Console Inspect a Url
description: >-
Inspects a URL to retrieve detailed index status, crawl information,
mobile usability findings, and rich results status. Returns the most
recent indexing data Google has for the specified URL. The URL must
belong to a property that the authenticated user has access to. This
endpoint uses the v1 URL path, separate from the webmasters/v3 paths
used by other Search Console endpoints.
tags:
- URL Inspection
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InspectUrlIndexRequest'
example:
inspectionUrl: https://example.com/page
siteUrl: https://example.com/
languageCode: en-US
responses:
'200':
description: URL inspection results.
content:
application/json:
schema:
$ref: '#/components/schemas/InspectUrlIndexResponse'
examples:
Inspecturl200Example:
summary: Default inspectUrl 200 response
x-microcks-default: true
value:
inspectionResult:
inspectionResultLink: https://www.example.com
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
OAuth2:
type: oauth2
description: >-
OAuth 2.0 authentication for accessing Google Search Console data.
Requires the webmasters or webmasters.readonly scope depending on
the operation.
flows:
authorizationCode:
authorizationUrl: https://accounts.google.com/o/oauth2/v2/auth
tokenUrl: https://oauth2.googleapis.com/token
scopes:
https://www.googleapis.com/auth/webmasters: View and manage Search Console data for your verified sites
https://www.googleapis.com/auth/webmasters.readonly: View Search Console data for your verified sites
parameters:
SiteUrl:
name: siteUrl
in: path
required: true
description: >-
The site's URL, including protocol. For domain properties, use the
format sc-domain:example.com. For URL-prefix properties, use the
full URL (e.g., https://example.com/). The URL must be encoded.
schema:
type: string
example: https://example.com/
Feedpath:
name: feedpath
in: path
required: true
description: >-
The URL of the sitemap. Must be the full URL, including the protocol
(e.g., https://example.com/sitemap.xml). The URL must be encoded.
schema:
type: string
format: uri
example: https://example.com/sitemap.xml
responses:
BadRequest:
description: The request was invalid or cannot be served.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Authentication required or invalid credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Insufficient permissions for the requested operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
TooManyRequests:
description: Rate limit exceeded. Retry after the specified delay.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
SearchAnalyticsQueryRequest:
type: object
description: >-
Request body for querying search analytics data. Defines the date
range, dimensions, filters, and aggregation type for the query.
required:
- startDate
- endDate
properties:
startDate:
type: string
format: date
description: >-
Start date of the requested date range, in YYYY-MM-DD format.
Must be less than or equal to the end date. Data is available
starting from the date the site was added to Search Console.
example: '2026-01-15'
endDate:
type: string
format: date
description: >-
End date of the requested date range, in YYYY-MM-DD format.
Must be greater than or equal to the start date. There is a
processing delay of approximately 2-3 days.
example: '2026-01-15'
dimensions:
type: array
description: >-
Zero or more dimensions to group results by. Results are grouped
in the order that dimensions are specified. Valid dimensions are
date, query, page, country, device, and searchAppearance.
items:
type: string
enum:
- date
- query
- page
- country
- device
- searchAppearance
example: []
type:
type: string
description: >-
Filter results to the specified search type. Defaults to web.
enum:
- web
- image
- video
- news
- discover
- googleNews
default: web
example: web
dimensionFilterGroups:
type: array
description: >-
Zero or more groups of dimension filters. All filter groups are
ANDed together. Within a group, filters are combined using the
group type (AND by default).
items:
$ref: '#/components/schemas/DimensionFilterGroup'
example: []
aggregationType:
type: string
description: >-
How data is aggregated. If auto, data is aggregated by property
type. If byPage, all data is aggregated by page. If byProperty,
all data is aggregated by property.
enum:
- auto
- byPage
- byProperty
default: auto
example: auto
rowLimit:
type: integer
description: >-
Maximum number of rows to return. Valid range is 1 to 25000.
Default is 1000.
minimum: 1
maximum: 25000
default: 1000
example: 10
startRow:
type: integer
description: >-
Zero-based index of the first row in the response. Must be a
non-negative number. Default is 0.
minimum: 0
default: 0
example: 10
dataState:
type: string
description: >-
The data state to filter on. If set to final, only finalized
data is returned. If set to all, both finalized and fresh data
are included.
enum:
- final
- all
default: final
example: final
DimensionFilterGroup:
type: object
description: A group of dimension filters applied to the query.
properties:
groupType:
type: string
description: How filters within this group are combined.
enum:
- and
default: and
example: and
filters:
type: array
description: Filters within this group.
items:
$ref: '#/components/schemas/DimensionFilter'
example: []
DimensionFilter:
type: object
description: A filter on a specific dimension.
required:
- dimension
- expression
properties:
dimension:
type: string
description: The dimension to filter on.
enum:
- query
- page
- country
- device
- searchAppearance
example: query
operator:
type: string
description: >-
How to filter. The contains operator performs a case-insensitive
substring match. The equals operator performs a case-sensitive
exact match. The notContains and notEquals operators are the
negations of contains and equals respectively. The
includingRegex and excludingRegex operators use RE2 syntax.
enum:
- contains
- equals
- notContains
- notEquals
- includingRegex
- excludingRegex
default: equals
example: contains
expression:
type: string
description: >-
The value to filter on. For country, use the 3-letter country
code (ISO 3166-1 alpha-3). For device, use DESKTOP, MOBILE,
or TABLET.
example: example_value
SearchAnalyticsQueryResponse:
type: object
description: Response for a search analytics query.
properties:
rows:
type: array
description: >-
A list of rows grouped by the requested dimensions. Rows are
ordered by click count descending. If no data is available for
the specified date range and filters, this field is omitted.
items:
$ref: '#/components/schemas/SearchAnalyticsRow'
example: []
responseAggregationType:
type: string
description: How the results were aggregated.
enum:
- auto
- byPage
- byProperty
example: auto
SearchAnalyticsRow:
type: object
description: >-
A single row of search analytics data. Contains dimension keys and
their associated metric values.
properties:
keys:
type: array
description: >-
A list of dimension values for this row, in the same order as
the dimensions specified in the request. For country, the value
is a 3-letter country code. For device, the value is DESKTOP,
MOBILE, or TABLET.
items:
type: string
example: []
clicks:
type: number
description: >-
The number of clicks from Google Search results that landed on
the property.
example: 42.5
impressions:
type: number
description: >-
The number of times a link to the property appeared in search
results and was seen by a user (not necessarily scrolled into
view).
example: 42.5
ctr:
type: number
format: double
description: >-
Click-through rate: the ratio of clicks to impressions, expressed
as a decimal between 0 and 1.
example: 42.5
position:
type: number
format: double
description: >-
The average position of the property in search results, where
1 is the topmost position. The value is averaged across all
queries and pages.
example: 42.5
SitesListResponse:
type: object
description: Response for listing Search Console sites.
properties:
siteEntry:
type: array
description: List of verified sites.
items:
$ref: '#/components/schemas/WmxSite'
example: []
WmxSite:
type: object
description: >-
A Search Console site resource representing a verified property.
Properties can be URL-prefix properties or domain properties.
properties:
siteUrl:
type: string
description: >-
The URL of the site. For URL-prefix properties, this is the
full URL including protocol. For domain properties, this uses
the sc-domain: prefix (e.g., sc-domain:example.com).
example: https://www.example.com
permissionLevel:
type: string
description: >-
The user's permission level for this site in Search Console.
enum:
- siteOwner
- siteFullUser
- siteRestrictedUser
- siteUnverifiedUser
example: siteOwner
SitemapsListResponse:
type: object
description: Response for listing sitemaps.
properties:
sitemap:
type: array
description: List of sitemaps for the site.
items:
$ref: '#/components/schemas/WmxSitemap'
example: []
WmxSitemap:
type: object
description: >-
Information about a sitemap submitted to Search Console. Includes
processing status, error counts, and content details.
properties:
path:
type: string
format: uri
description: The URL of the sitemap.
example: https://www.example.com
lastSubmitted:
type: string
format: date-time
description: >-
Date and time when the sitemap was last submitted to Search Console.
example: '2026-01-15T10:30:00Z'
isPending:
type: boolean
description: Whether the sitemap is still being processed.
example: true
isSitemapsIndex:
type: boolean
description: Whether this is a sitemap index file.
example: true
type:
type: string
description: The type of content in the sitemap.
enum:
- atomFeed
- rssFeed
- sitemap
- urlList
- patternSitemap
- notSitemap
example: atomFeed
lastDownloaded:
type: string
format: date-time
description: >-
Date and time when the sitemap was last downloaded by Google.
example: '2026-01-15T10:30:00Z'
warnings:
type: integer
description: Number of warnings for the sitemap.
example: 10
errors:
type: integer
description: Number of errors for the sitemap.
example: 10
contents:
type: array
description: >-
Content details for this sitemap, broken down by content type.
items:
$ref: '#/components/schemas/WmxSitemapContent'
example: []
WmxSitemapContent:
type: object
description: Content type information within a sitemap.
properties:
type:
type: string
description: The type of content in this sitemap segment.
enum:
- web
- image
- video
- news
- mobile
- androidApp
- pattern
- iosApp
- dataFeedElement
example: web
submitted:
type: integer
format: int64
description: The number of URLs of this type submitted in the sitemap.
example: 10
indexed:
type: integer
format: int64
description: >-
The number of URLs of this type that have been indexed by Google.
example: 10
InspectUrlIndexRequest:
type: object
description: Request body for the URL Inspection API.
required:
- inspectionUrl
- siteUrl
properties:
inspectionUrl:
type: string
format: uri
description: >-
The fully qualified URL to inspect. Must be under the specified
site property.
example: https://www.example.com
siteUrl:
type: string
description: >-
The URL of the site property in Search Console. Can be a
URL-prefix property (e.g., https://example.com/) or a domain
property (e.g., sc-domain:example.com).
example: https://www.example.com
languageCode:
type: string
description: >-
Optional BCP-47 language code for the response. If not specified,
the response will be in English.
example: en-US
InspectUrlIndexResponse:
type: object
description: Response from the URL Inspection API.
properties:
inspectionResult:
$ref: '#/components/schemas/UrlInspectionResult'
UrlInspectionResult:
type: object
description: >-
The aggregated inspection result for a URL, including index status,
crawl information, mobile usability, and rich results.
properties:
inspectionResultLink:
type: string
format: uri
description: >-
Link to the URL inspection result in the Search Console UI.
example: https://www.example.com
indexStatusResult:
$ref: '#/components/schemas/IndexStatusInspectionResult'
mobileUsabilityResult:
$ref: '#/components/schemas/MobileUsabilityInspectionResult'
richResultsResult:
$ref: '#/components/schemas/RichResultsInspectionResult'
IndexStatusInspectionResult:
type: object
description: Index status inspection results for a URL.
properties:
verdict:
type: string
description: >-
The overall verdict for the index status of the URL.
enum:
- VERDICT_UNSPECIFIED
- PASS
- PARTIAL
- FAIL
- NEUTRAL
example: VERDICT_UNSPECIFIED
coverageState:
type: string
description: >-
The coverage state of the URL, indicating whether and how it
appears in the index. Common values include Submitted and
indexed, Crawled - currently not indexed, Discovered -
currently not indexed, and URL is unknown to Google.
example: example_value
robotsTxtState:
type: string
description: >-
Whether the page is blocked by robots.txt.
enum:
- ROBOTS_TXT_STATE_UNSPECIFIED
- ALLOWED
- DISALLOWED
example: ROBOTS_TXT_STATE_UNSPECIFIED
indexingState:
type: string
description: >-
Whether the page is blocked from indexing via noindex directives.
enum:
- INDEXING_STATE_UNSPECIFIED
- INDEXING_ALLOWED
- BLOCKED_BY_META_TAG
- BLOCKED_BY_HTTP_HEADER
- BLOCKED_BY_ROBOTS_TXT
example: INDEXING_STATE_UNSPECIFIED
lastCrawlTime:
type: string
format: date-time
description: >-
The last time this URL was crawled by Google, in RFC 3339 format.
example: '2026-01-15T10:30:00Z'
pageFetchState:
type: string
description: >-
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/google-search-console/refs/heads/main/openapi/google-search-console-api-openapi.yml