Quickstart: Enable Cloud Location Finder and run a query

This page shows you how to enable Cloud Location Finder using the Google Cloud CLI and find cloud locations by proximity, jurisdiction, and carbon footprint. You can find locations using HTTP requests or Google Cloud CLI commands.

Before you begin

Install the Google Cloud CLI.
To initialize the Google Cloud CLI, run the following command:
```
gcloud init
```

Enable the Cloud Location Finder API:

gcloud services enable cloudlocationfinder.googleapis.com  --project PROJECT

Add the cloudlocationfinder.viewer role:
```
gcloud projects add-iam-policy-binding PROJECT \
    --member USER_IDENTIFIER \
    --role roles/cloudlocationfinder.viewer
```
- Replace PROJECT with your project ID.
- Replace USER_IDENTIFIER with the identifier for your user account. For example, user:myemail@example.com.

Explore common Cloud Location Finder queries

Cloud Location Finder lets you query the cloud location repository to identify nearby cloud locations based on proximity, territory code, or Google carbon free energy (CFE%) consumption. The following sections provide common examples of how to interact with the Cloud Location Finder repository.

Cloud Location Finder uses gRPC Transcoding syntax.

Find the nearest cloud zone

Use this query to identify the nearest Google Cloud zone to a cloud location using proximity data for a cloud provider that you specify.

Replace PROJECT with your project ID.
Replace CLOUD_REGION with the source cloud region to find the closest location to, including the cloud provider prefix. For example, gcp-us-central1 or aws-us-east-1.
Replace CLOUD_PROVIDER with the cloud provider to find the closest location to. For example, AWS or GCP.

HTTP

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://cloudlocationfinder.googleapis.com/v1alpha/projects/PROJECT/locations/global/cloudLocations:search?source_cloud_location=projects/PROJECT/locations/global/cloudLocations/CLOUD_REGION&query=cloud_provider=CLOUD_PROVIDER_CLOUD_PROVIDER%20AND%20cloud_location_type=CLOUD_LOCATION_TYPE_ZONE&page_size=1"

gcloud

gcloud alpha cloudlocationfinder cloud-locations search
--source-cloud-location=CLOUD_REGION
--query="cloud_provider=CLOUD_PROVIDER_CLOUD_PROVIDER AND cloud_location_type=CLOUD_LOCATION_TYPE_ZONE" --limit=1

Find regions within a specific territory

Use this query to identify regions within a specific territory, or jurisdiction, using a territory code that you provide.

HTTP

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://cloudlocationfinder.googleapis.com/v1alpha/projects/PROJECT/locations/global/cloudLocations:search?source_cloud_location=projects/PROJECT/locations/global/cloudLocations/CLOUD_REGION&query=cloud_provider=CLOUD_PROVIDER_CLOUD_PROVIDER%20AND%20cloud_location_type=CLOUD_LOCATION_TYPE_REGION&page_size=1"

gcloud

gcloud alpha cloudlocationfinder cloud-locations list
--source-cloud-location=CLOUD_REGION
--query="cloud_provider=CLOUD_PROVIDER_CLOUD_PROVIDER AND cloud_location_type=CLOUD_LOCATION_TYPE_REGION" --limit=1

List cloud locations that minimize carbon footprint

Use this query to identify regions with the lowest carbon footprint based on Carbon free energy for Google Cloud regions.

HTTP

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://cloudlocationfinder.googleapis.com/v1alpha/projects/PROJECT/locations/global/cloudLocations?query=cloud_provider=CLOUD_PROVIDER_CLOUD_PROVIDER%20AND%20cloud_location_type=CLOUD_LOCATION_TYPE_REGION&page_size=5"

gcloud

gcloud alpha cloudlocationfinder cloud-locations list
--query="cloud_provider=CLOUD_PROVIDER_CLOUD_PROVIDER AND cloud_location_type=CLOUD_LOCATION_TYPE_REGION"
--limit=5

What's next

Review supported locations
Learn about the location search query syntax
Check out the API reference