Configure data locality with regional endpoints

This page describes how to configure the Firestore client libraries to use a regional or multi-regional endpoint.

When you use Firestore client libraries, you can use any of the following endpoints:

  • Global endpoint: By default, the Firestore client libraries send API requests to a global service endpoint named firestore.googleapis.com. The global service endpoint routes the request to your database. During routing, a request might pass through a server in a location that's different from your database location.

  • Regional endpoint: A regional endpoint enforces restrictions ensuring that data is transmitted, stored and processed in a specified Google Cloud region. To ensure that the service endpoint processes your app's Firestore requests in the same region as your database, specify a regional endpoint in the client library.

  • Multi-regional endpoint: A multi-regional endpoint enforces restrictions ensuring that data is transmitted, stored and processed in a specified Google Cloud multi-region. To ensure that the service endpoint processes your app's Firestore requests in the same multi-region as your database, specify a multi-regional endpoint in the client library.

Set a regional or multi-regional endpoint

The method for configuring a regional or multi-regional endpoint is the same: you provide the endpoint string when initializing the client library. The following examples show how to set the endpoint string using a regional endpoint (firestore.us-central1.rep.googleapis.com). To use a multi-regional endpoint, provide a multi-regional endpoint string corresponding to your database's location (for example, firestore.us.rep.googleapis.com for nam5).

Java

To authenticate to Firestore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 


import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.firestore.Firestore;
import com.google.cloud.firestore.FirestoreOptions;


/**
 * Demonstrate how to set a regional endpoint.
 */
public class RegionalEndpointSnippets {

  /**
   * Create a client with a regional endpoint.
   **/
  public Firestore regionalEndpoint(String projectId, String endpoint) throws Exception {
    FirestoreOptions firestoreOptions =
        FirestoreOptions.newBuilder()
            .setProjectId(projectId)
            .setCredentials(GoogleCredentials.getApplicationDefault())
            // set endpoint like firestore.us-central1.rep.googleapis.com:443
            .setHost(endpoint)
            .build();
    Firestore dbWithEndpoint = firestoreOptions.getService();

    return dbWithEndpoint;
  }

}

Python

To authenticate to Firestore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 

ENDPOINT = "firestore.africa-south1.rep.googleapis.com"
client_options = ClientOptions(api_endpoint=ENDPOINT)
db = firestore.Client(client_options=client_options)

cities_query = db.collection("cities").limit(2).get()
for r in cities_query:
    print(r)

Regional and multi-regional endpoint semantics

Regional Endpoints (REP):

Firestore supports regional endpoints for the regional locations listed here Firestore locations.

Use the following format to define regional endpoints:

Java

    firestore.REGION_NAME.rep.googleapis.com:443

Make sure that the port number is defined along with the endpoint.

Python

    firestore.REGION_NAME.rep.googleapis.com

Go

    firestore.REGION_NAME.rep.googleapis.com:443

Make sure that the port number is defined along with the endpoint.

Replace REGION_NAME with the name of a regional hostname.

Some examples of hostnames are:

  • firestore.us-central1.rep.googleapis.com
  • firestore.europe-west1.rep.googleapis.com

Multi-regional Endpoints (MREP)

For multi-regional endpoints, use us for locations nam5 and nam7, and eu for location eur3 (see Multi-regional locations).

Java

    firestore.us.rep.googleapis.com:443
    firestore.eu.rep.googleapis.com:443

Make sure that the port number is defined along with the endpoint.

Python

    firestore.us.rep.googleapis.com
    firestore.eu.rep.googleapis.com

Go

    firestore.us.rep.googleapis.com:443
    firestore.eu.rep.googleapis.com:443

Make sure that the port number is defined along with the endpoint.

Limitations

Locational Endpoints (Deprecated)

Locational endpoints are now deprecated. Use regional or multi-regional endpoints instead.

Firestore previously supported locational endpoints with the following format:

Java

  REGION_NAME-firestore.googleapis.com:443

Make sure that the port number is defined along with the endpoint.

Python

  REGION_NAME-firestore.googleapis.com

Go

  REGION_NAME-firestore.googleapis.com:443

Make sure that the port number is defined along with the endpoint.

Replace REGION_NAME with the name of a regional or multi-regional hostnames.

Some examples of hostnames are:

  • eur3-firestore.googleapis.com
  • nam5-firestore.googleapis.com
  • europe-west6-firestore.googleapis.com
  • asia-northeast2-firestore.googleapis.com

For a complete list of multi-regional and regional hostnames, see Firestore locations.

Restrict global API endpoint usage

To help enforce the use of regional and multi-regional endpoints, use the constraints/gcp.restrictEndpointUsage organization policy constraint to block requests to the global API endpoint. For more information, see Restricting endpoint usage.

What's next