Invoking the API

This document describes how to use the Google Site Verification API.

Invoking the API

Request format

Most of the supported Site Verification operations map directly to REST HTTP verbs (GET, POST, PUT, DELETE), as described in Google Site Verification API operations.

The specific format for Google Site Verification API URIs are:

https://www.googleapis.com/siteVerification/v1/webResource/resourceID?parameters

where resourceID is the identifier for a web resource, parameters are any parameters to apply to the query. The actual parameters you use varies depending on which operation you are performing. Additionally, if you are using OAuth 2.0, you should set access_token in these parameters.

List queries do not require a resourceID, so the format is:

https://www.googleapis.com/siteVerification/v1/webResource?parameters

You can make calls to the getToken operation by its own unique URI. The format for a call to getToken is:

https://www.googleapis.com/siteVerification/v1/token?parameters

Data format

The Google Site Verification API returns data in JSON format.

JSON (JavaScript Object Notation) is a common, language-independent data format that provides a simple text representation of arbitrary data structures. For more information, see json.org.

Operations summary

You can invoke six different methods on collections and resources in the Google Site Verification API, as described in the following table. The API URLs are relative to https://www.googleapis.com/siteVerification/v1.

Operation Description URL and syntax
list

Lists all resources within the authenticated user's collection.

GET /webResource

See example list request.

insert

Verifies a site or domain. If successful, inserts a new web resource into the user's collection.

Request body: See Web Resource.

Query parameter: verificationMethod. The verification method to use for this request. Possible values: FILE, META, ANALYTICS, TAG_MANAGER, DNS_TXT, DNS_CNAME

POST /webResource

See example insert request.

get

Gets the latest data for a specific web resource.

GET /webResource/resourceID

See example get request

update

Modifies the list of owners for a specific resource.

Request body: See Web Resource.

Notes:

  • You can't remove the authenticated user from the owners list using update. Use delete instead.
  • You can remove from the owners list any user who does not have a verification token on the site.

PUT /webResource/resourceID

See example update request.

delete

Removes a resource from the user's collection (unverifies that the site belongs to the user).

Notes:

  • You must first remove all of the authenticated user's verification tokens from the site or domain prior to calling delete. If any tokens still exist, an HTTP 400 (Bad Request) error is returned.
  • Deletion only affects ownership data for the authenticated user. All other users, whether they were delegated or independently verified, retain ownership following deletion.

DELETE /webResource/resourceID

See example delete request.

getToken

Gets the verification token to place on the authenticated user's website.

Request body:

  • identifier: The site URL or domain name.
  • type: The type of resource to verify. Possible values: SITE, INET_DOMAIN.
  • verificationMethod: The method to use when verifying your site. Possible values: FILE, META, ANALYTICS, TAG_MANAGER, DNS_TXT, DNS_CNAME

POST /token

See example getToken request.

Example API calls

This section assumes that you (the developer) are also the authenticated user, as would be the case when you first try out the API with your own test data.

Verify a new site

To verify a site,

  1. First request a verification token by calling getToken.
  2. Place the token on your site using whatever method you choose.
  3. Ask Google to verify that the site is yours, using the insert operation.

getToken (requires authorization)

POST https://www.googleapis.com/siteVerification/v1/token?access_token=oauth2-token

Request:

POST https://www.googleapis.com/siteVerification/v1/token?access_token=oauth2-token
Content-Type: application/json

{
  "verificationMethod": "FILE",
  "site": {
    "identifier": "http://www.example.com",
    "type": "SITE"
  }
}

Response:

{
  "token": "google12cfc68677988bb4.html",
  "method": "FILE"
}

Insert (requires authorization)

POST https://www.googleapis.com/siteVerification/v1/webResource?verificationMethod=FILE&access_token=oauth2-token

Request:

POST https://www.googleapis.com/siteVerification/v1/webResource?verificationMethod=FILE&access_token=oauth2-token
Content-Type: application/json

{
  "site": {
    "identifier": "http://www.example.com",
    "type": "SITE"
  }
}

Response:

{
  "owners": [
    "myself@example.com",
  ],
  "id": "http%3A%2F%2Fwww.example.com%2F",
  "site": {
    "identifier": "http://www.example.com/",
    "type": "SITE"
  }
}

Retrieve information for verified web resources

You can retrieve the full list of your verified sites and domains by calling list. You can retrieve information for a single web resource by calling get.

List (requires authorization)

GET https://www.googleapis.com/siteVerification/v1/webResource?access_token=oauth2-token

Request:

GET https://www.googleapis.com/siteVerification/v1/webResource?access_token=oauth2-token

Response:

{
  "items": [
    {
      "owners": [
        "myself@example.com",
      ],
      "id": "http%3A%2F%2Fwww.example.com%2F",
      "site": {
        "identifier": "http://www.example.com/site1",
        "type": "SITE"
      }
    },
    {
      "owners": [
        "myself@example.com",
      ],
      "id": "http%3A%2F%2Fwww.example.com%2F",
      "site": {
        "identifier": "http://www.example.com/site2",
        "type": "SITE"
      }
    }
  ]
}

Get (requires authorization)

GET https://www.googleapis.com/siteVerification/v1/webResource/http%3A%2F%2Fwww.example.com%2F?access_token=oauth2-token

Request:

GET https://www.googleapis.com/siteVerification/v1/webResource/http%3A%2F%2Fwww.example.com%2F?access_token=oauth2-token

Response:

{
  "owners": [
    "myself@example.com",
  ],
  "id": "http%3A%2F%2Fwww.example.com%2F",
  "site": {
    "identifier": "http://www.example.com/",
    "type": "SITE"
  }
}

Modify verification information

You can delegate and revoke ownership by calling update. You can remove ownership for yourself by calling delete.

Update (requires authorization)

PUT https://www.googleapis.com/siteVerification/v1/webResource/http%3A%2F%2Fwww.example.com%2F?access_token=oauth2-token

Request:

PUT https://www.googleapis.com/siteVerification/v1/webResource/http%3A%2F%2Fwww.example.com%2F?access_token=oauth2-token
Content-Type: application/json

{
  "owners": [
    "myself@example.com",
    "another@example.com",
  ],
  "id": "http%3A%2F%2Fwww.example.com%2F",
  "site": {
    "identifier": "http://www.example.com",
    "type": "SITE"
  }
}

Response:

{
  "owners": [
    "myself@example.com",
    "another@example.com",
  ],
  "id": "http%3A%2F%2Fwww.example.com%2F",
  "site": {
    "identifier": "http://www.example.com/",
    "type": "SITE"
  }
}

Delete (requires authorization)

DELETE https://www.googleapis.com/siteVerification/v1/webResource/http%3A%2F%2Fwww.example.com%2F?access_token=oauth2-token

Request:

DELETE https://www.googleapis.com/siteVerification/v1/webResource/http%3A%2F%2Fwww.example.com%2F?access_token=oauth2-token

Response:

HTTP 204 (No Content) status code, indicating success.