WebService::GoogleAPI::Client::Discovery - Google API discovery service


version 0.24_001



Not using Swagger but it is interesting - for Swagger Specs.

WebService::GoogleAPI::Client - contains code for parsing discovery structures

includes a chi property that is an instance of CHI using File Driver to cache discovery resources for 30 days

say $client-dicovery->chi->root_dir(); ## provides full file path to temp storage location used for caching



  my $hashref = $disco->get_with_cache($url, $force, $authenticate)

Retrieves the given API URL, retrieving and caching the returned JSON. If it gets a 403 Unauthenticated error, then it will try again using the credentials that are save on this instances 'ua'.

If passed a truthy value for $force, then will not use the cache. If passed a truthy value for $authenticate, then will make the request with credentials.


  my $hashref = $disco->discover_all($force, $authenticate)

Return details about all Available Google APIs as provided by Google or in CHI Cache. Does the fetching with get_with_cache, and arguments are as above.

On Success: Returns HASHREF with keys discoveryVersion,items,kind On Failure: dies a horrible death. You probably don't want to continue in that case.

SEE ALSO: available_APIs, list_of_available_google_api_ids


Return hashref keyed on api name, with arrays of versions, links to documentation, and links to the url for that version's API document.

      youtube => {
        version           => [ 'v3', ... ]
        documentationLink => [ ...,  ... ] ,
        discoveryRestUrl  => [ ...,  ... ] ,
      gmail => {

Used internally to pull relevant discovery documents.


Allows you to augment the cached stored version of the discovery structure

    $augmented_document = $disco->augment_with({
      'version'   => 'v4',
      'preferred' => 1,
      'title'     => 'Google My Business API',
      'description' => 'The Google My Business API provides an interface for managing business location information on Google.',
      'id'                => 'mybusiness:v4',
      'kind'              => 'discovery#directoryItem',
      'documentationLink' => "",
      'icons'             => {
        "x16" => "",
        "x32" => ""
      'discoveryRestUrl' => '',
      'name' => 'mybusiness'

This can also be used to overwrite the cached structure.

Can also be called as augment_discover_all_with_unlisted_experimental_api, which is being deprecated for being plain old too long.


Return 1 if Google Service API ID is described by Google API discovery. Otherwise return 0

  print $disco->service_exists('calendar');  # 1
  print $disco->service_exists('someapi');  # 0

Note that most Google APIs are fully lowercase, but some are camelCase. Please check the documentation from Google for reference.


  Show available versions of particular API described by api id passed as parameter such as 'gmail'

  $disco->available_versions('calendar');  # ['v3']
  $disco->available_versions('youtubeAnalytics');  # ['v1','v1beta1']

  Returns arrayref


return latest stable verion of API

  $d->available_versions('calendar');  # ['v3']
  $d->latest_stable_version('calendar');  # 'v3'

  $d->available_versions('tagmanager');  # ['v1','v2']
  $d->latest_stable_version('tagmanager');  # ['v2']

  $d->available_versions('storage');  # ['v1','v1beta1', 'v1beta2']
  $d->latest_stable_version('storage');  # ['v1']


  my $hashref = $disco->process_api_version('gmail')   
     # { api => 'gmail', version => 'v1' }
  my $hashref = $disco->process_api_version({ api => 'gmail' })   
     # { api => 'gmail', version => 'v1' }
  my $hashref = $disco->process_api_version('gmail:v2') 
     # { api => 'gmail', version 'v2' }

Takes a version string and breaks it into a hashref. If no version is given, then default to the latest stable version in the discover document.


returns the cached version if avaiable in CHI otherwise retrieves discovery data via HTTP, stores in CHI cache and returns as a Perl data structure.

    my $hashref = $self->get_api_document( 'gmail' );
    my $hashref = $self->get_api_document( 'gmail:v3' );
    my $hashref = $self->get_api_document( 'gmail:v3.users.list' );
    my $hashref = $self->get_api_document( { api=> 'gmail', version => 'v3' } );

NB: if deeper structure than the api_id is provided then only the head is used so get_api_document( 'gmail' ) is the same as get_api_document( 'gmail.some.child.method' ) returns the api discovery specification structure ( cached by CHI ) for api id (eg 'gmail') returns the discovery data as a hashref, an empty hashref on certain failing conditions or croaks on critical errors.

Also available as get_api_discovery_for_api_id, which is being deprecated.


    $disco->get_method_details($tree, $api_version)

returns a hashref representing the discovery specification for the method identified by $tree in dotted API format such as texttospeech.text.synthesize

Dies a horrible death if not found.

Also available as extract_method_discovery_detail_from_api_spec, but the long name is being deprecated in favor of the more compact one.


Returns a hashref keyed on the Google service API Endpoint in dotted format. The hashed content contains a structure representing the corresponding discovery specification for that method ( API Endpoint )


    methods_available_for_google_api_id('gmail.users.settings.delegates.get', 'v1');


Returns an array list of all the available API's described in the API Discovery Resource that is either fetched or cached in CHI locally for 30 days.

    my $r = $agent->list_api_ids();
    print "List of API Services ( comma separated): $r\n";

    my @list = $agent->list_api_ids();

Formerly was list_of_available_google_api_ids, which will now give a deprecation warning to switch to list_api_ids.


  • Veesh Goldman <>

  • Peter Scott <>


This software is Copyright (c) 2017-2021 by Peter Scott and others.

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004