Stay organized with collectionsSave and categorize content based on your preferences.
The Discovery API provides a list of Google APIs for retrieving a machine-readable "Discovery
document" metadata for each API.
This document is intended for developers who want to write client libraries, IDE plugins, and
other tools for interacting with Google APIs.
Discovery Service Background
Concepts
The Google APIs Discovery Service is built upon two basic concepts:
APIs Directory: A list of all APIs that are supported by the
APIs Discovery Service. Each directory entry shows details about a supported API, including itsname, a briefdescriptionof what it does, and adocumentation
link. An API can have multiple Directory entries, one for each of its supported
versions.
Discovery document: A machine-readable description of a particular API.
The Discovery document describes the surface for a particular version of an API. The
document provides details on how to access the various methods of each API via RESTful HTTP
calls. A Discovery document includes descriptions of the data and methods associated with
the API, as well as information about available OAuth scopes, and descriptions of schemas,
methods, parameters and available parameter values.
Data model
A resource is an individual data entity with a unique identifier. The Google APIs Discovery Service operates on
two types of resources, based on the above concepts.
APIs Directory List: A list of APIs
Each directory entry contains an APIname/versionpair with the
following information:
Identification and description information,: name, version, title, and
description.
Documentation information: icons and a documentation link.
Status information, including status labels, and an indication as to
whether or not this is the preferred version of the API.
Discovery document link, the URI of the discovery document for this API
(given as a full URL—for example,https://serviceusage.googleapis.com/$discovery/rest?version=v1).
Discovery Document resource: A machine-readable description of a particular API
In addition to the information provided in the APIs Directory, a Discovery document also
includes:
Schemas, which is a list of API resource schemas that describe the data you
have access to in each API; the Google APIs Discovery Service schemas are based onJSON Schema.
Methods, including a list of API methods and available parameters for each
method.
OAuth scopes, which identifies the list of OAuth scopes available for this
API.
Inline documentation, which provides brief descriptions of schemas,
methods, parameters and available parameter values.
The single Directory Collection is the conceptual container of the single APIs Directory
resource, and the Discovery Document resources for each supported API.
Operations
You can invoke two different methods on collections and resources in the Google APIs Discovery Service, as
described in the following table.
Operation
Description
REST HTTP mappings
list
Lists all supported APIs.
GETon the Directory resource URI.
Calling style
REST
The supported Google APIs Discovery Service operations map directly to theRESTHTTPGETverb, as described inOperations.
The specific format for Google APIs Discovery Service URIs are:
https://API/$discovery/rest?version=VERSION
whereAPIis the identifier for a Discovery Document resource, andVERSIONis the identifier of the particular version of the API.
Here are a couple of examples of how this works in the Google APIs Discovery Service.
List all the Google APIs Discovery Service supported APIs:
GET https://discovery.googleapis.com/discovery/v1/apis
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-06-16 UTC."],[[["\u003cp\u003eThe Discovery API provides machine-readable metadata, called "Discovery documents," for various Google APIs, facilitating the creation of client libraries and tools for interacting with them.\u003c/p\u003e\n"],["\u003cp\u003eThe service consists of an APIs Directory, listing all supported APIs with descriptions and documentation links, and Discovery documents, detailing each API version's methods, data schemas, and OAuth scopes.\u003c/p\u003e\n"],["\u003cp\u003eEach directory entry includes an API name/version pair, along with identification, documentation, status information, and the Discovery document link.\u003c/p\u003e\n"],["\u003cp\u003eDiscovery documents offer comprehensive details beyond the directory, including API resource schemas, available methods and parameters, OAuth scopes, and inline documentation.\u003c/p\u003e\n"],["\u003cp\u003eThe Google APIs Discovery Service supports \u003ccode\u003eGET\u003c/code\u003e requests to list all APIs in the directory and retrieve specific Discovery documents, with public APIs not requiring authentication and private ones needing API keys.\u003c/p\u003e\n"]]],[],null,["# Overview of the Discovery API\n\nThe Discovery API provides a list of Google APIs for retrieving a machine-readable \"Discovery\ndocument\" metadata for each API.\n\n\nThis document is intended for developers who want to write client libraries, IDE plugins, and\nother tools for interacting with Google APIs.\n\nDiscovery Service Background\n----------------------------\n\n### Concepts\n\nThe Google APIs Discovery Service is built upon two basic concepts:\n\n- **APIs Directory** : A list of all APIs that are supported by the APIs Discovery Service. Each directory entry shows details about a supported API, including its *name* , a brief *description* of what it does, and a *documentation\n link*. An API can have multiple Directory entries, one for each of its supported versions.\n- **Discovery document**: A machine-readable description of a particular API. The Discovery document describes the surface for a particular version of an API. The document provides details on how to access the various methods of each API via RESTful HTTP calls. A Discovery document includes descriptions of the data and methods associated with the API, as well as information about available OAuth scopes, and descriptions of schemas, methods, parameters and available parameter values.\n\n### Data model\n\n\nA resource is an individual data entity with a unique identifier. The Google APIs Discovery Service operates on\ntwo types of resources, based on the above concepts.\n\n#### APIs Directory List: A list of APIs\n\n\nEach directory entry contains an API **name** /**version** pair with the\nfollowing information:\n\n- **Identification and description information,**: name, version, title, and description.\n- **Documentation information**: icons and a documentation link.\n- **Status information**, including status labels, and an indication as to whether or not this is the preferred version of the API.\n- **Discovery document link** , the URI of the discovery document for this API (given as a full URL---for example, `https://serviceusage.googleapis.com/$discovery/rest?version=v1`).\n\n#### Discovery Document resource: A machine-readable description of a particular API\n\n\nIn addition to the information provided in the APIs Directory, a Discovery document also\nincludes:\n\n- **Schemas** , which is a list of API resource schemas that describe the data you have access to in each API; the Google APIs Discovery Service schemas are based on [JSON Schema](https://json-schema.org/).\n- **Methods**, including a list of API methods and available parameters for each method.\n- **OAuth scopes**, which identifies the list of OAuth scopes available for this API.\n- **Inline documentation**, which provides brief descriptions of schemas, methods, parameters and available parameter values.\n\n\nThe single Directory Collection is the conceptual container of the single APIs Directory\nresource, and the Discovery Document resources for each supported API.\n\n### Operations\n\n\nYou can invoke two different methods on collections and resources in the Google APIs Discovery Service, as\ndescribed in the following table.\n\nCalling style\n-------------\n\n| **Note:** Public APIs *do not* need authentication. Private APIs require an [API key](https://cloud.google.com/docs/authentication/api-keys).\n\n### REST\n\n\nThe supported Google APIs Discovery Service operations map directly to the [REST](https://en.wikipedia.org/wiki/Representational_State_Transfer) HTTP\n`GET` verb, as described in [Operations](#background-operations).\n\nThe specific format for Google APIs Discovery Service URIs are: \n\n```\nhttps://API/$discovery/rest?version=VERSION\n```\n\n\nwhere \u003cvar translate=\"no\"\u003eAPI\u003c/var\u003e is the identifier for a Discovery Document resource, and\n\u003cvar translate=\"no\"\u003eVERSION\u003c/var\u003e is the identifier of the particular version of the API.\n\nHere are a couple of examples of how this works in the Google APIs Discovery Service.\n\nList all the Google APIs Discovery Service supported APIs: \n\n```\nGET https://discovery.googleapis.com/discovery/v1/apis\n```\n\n\n[Try it now in APIs Explorer!](//developers.google.com/apis-explorer/#p/discovery/v1/discovery.apis.list)\n\nGet the Discovery document for Service Usage API, version 1: \n\n```\nGET https://serviceusage.googleapis.com/$discovery/rest?version=v1\n```"]]
