Stay organized with collections
Save and categorize content based on your preferences.
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.
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.
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.
gcloud alpha cloudlocationfinder cloud-locations list \
--source-cloud-location=CLOUD_REGION \
--filter="cloud_provider=CLOUD_PROVIDER_CLOUD_PROVIDER AND cloud_location_type=CLOUD_LOCATION_TYPE_REGION" AND filter="territory_code=\"TERRITORY_CODE\"" \
--limit=1
List cloud locations that minimize carbon footprint
[[["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-09-04 UTC."],[],[],null,["# Quickstart: Enable Cloud Location Finder and run a query\n========================================================\n\nThis page shows you how to enable Cloud Location Finder using the\nGoogle Cloud CLI and find cloud locations by proximity, jurisdiction, and carbon\nfootprint. You can find locations using HTTP requests or Google Cloud CLI\ncommands.\n\nBefore you begin\n----------------\n\n1. [Install](/sdk/docs/install) the Google Cloud CLI.\n2. To [initialize](/sdk/docs/initializing) the Google Cloud CLI, run the following command: \n\n ```\n gcloud init\n ```\n| If you've already installed Google Cloud CLI previously, make sure you have the\n| latest available version by running `gcloud components update`.\n3. Enable the Cloud Location Finder API: \n\n ```\n gcloud services enable cloudlocationfinder.googleapis.com --project PROJECT\n ```\n4. Add the `cloudlocationfinder.viewer` role: \n\n ```\n gcloud projects add-iam-policy-binding PROJECT \\\n --member USER_IDENTIFIER \\\n --role roles/cloudlocationfinder.viewer\n ```\n - Replace \u003cvar label=\"project\" translate=\"no\"\u003ePROJECT\u003c/var\u003e with your project ID.\n - Replace \u003cvar label=\"user_identifier\" translate=\"no\"\u003eUSER_IDENTIFIER\u003c/var\u003e with the identifier for your user account. For example, user:myemail@example.com.\n\nExplore common Cloud Location Finder queries\n--------------------------------------------\n\nCloud Location Finder lets you query the cloud location repository to\nidentify nearby cloud locations based on [proximity](#proximity),\n[territory code](#jurisdiction), or [Google carbon free energy (CFE%)](#carbon)\nconsumption. The following sections provide common examples of how to interact\nwith the Cloud Location Finder repository.\n\nCloud Location Finder uses [gRPC Transcoding syntax](https://google.aip.dev/127).\n\n### Find the nearest cloud zone\n\nUse this query to identify the nearest Google Cloud zone to a cloud location\nusing proximity data for a cloud provider that you specify.\n\n- Replace \u003cvar label=\"project\" translate=\"no\"\u003ePROJECT\u003c/var\u003e with your project ID.\n- Replace \u003cvar label=\"cloud region\" translate=\"no\"\u003eCLOUD_REGION\u003c/var\u003e 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`.\n- Replace \u003cvar label=\"cloud provider\" translate=\"no\"\u003eCLOUD_PROVIDER\u003c/var\u003e with the cloud\n provider to find the closest location to. For example, `AWS` or `GCP`.\n\n### HTTP\n\n```\ncurl -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\"\n```\n\n### gcloud\n\n```\ngcloud alpha cloudlocationfinder cloud-locations search \\\n --source-cloud-location=CLOUD_REGION \\\n --query=\"cloud_provider=CLOUD_PROVIDER_CLOUD_PROVIDER AND cloud_location_type=CLOUD_LOCATION_TYPE_ZONE\" \\\n --limit=1\n```\n\n### Find regions within a specific territory\n\nUse this query to identify regions within a specific territory, or jurisdiction,\nusing a territory code that you provide. \n\n### HTTP\n\n```\ncurl -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%20AND%20territory_code=TERRITORY_CODE&page_size=1\"\n```\n\n### gcloud\n\n```\ngcloud alpha cloudlocationfinder cloud-locations list \\\n --source-cloud-location=CLOUD_REGION \\\n --filter=\"cloud_provider=CLOUD_PROVIDER_CLOUD_PROVIDER AND cloud_location_type=CLOUD_LOCATION_TYPE_REGION\" AND filter=\"territory_code=\\\"TERRITORY_CODE\\\"\" \\\n --limit=1\n```\n\n### List cloud locations that minimize carbon footprint\n\nUse this query to identify regions with the lowest carbon footprint based on\n[Carbon free energy for Google Cloud regions](/sustainability/region-carbon%22%3ECFE%20consumption).\n**Note:** CFE data is available for only Google Cloud locations. \n\n### HTTP\n\n```\ncurl -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\"\n```\n\n### gcloud\n\n```\ngcloud alpha cloudlocationfinder cloud-locations list \\\n --filter=\"cloud_provider=CLOUD_PROVIDER_CLOUD_PROVIDER AND cloud_location_type=CLOUD_LOCATION_TYPE_REGION\" \\\n --limit=5\n```\n\nWhat's next\n-----------\n\n- Review [supported locations](/location-finder/docs/overview#supported-locations)\n- Learn about the [location search query syntax](/location-finder/docs/syntax)\n- Check out the [API reference](/location-finder/docs/reference/rest)"]]
