Configure data locality with regional endpoints

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

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

• Global endpoint: By default, the Cloud 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 Cloud 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 stored and processed in a specified multi-region. To ensure that the service endpoint processes your app's Cloud 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 ).

  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 
 ; 
  
 } 
 } 
 
  RegionalEndpointSnippets 
 . 
 java 
 
 
 

  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 
 ) 
 
  snippets 
 . 
 py 
 
 
 

Regional and multi-regional endpoint semantics

Regional Endpoints (REP):

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

Use the following format to define regional endpoints:

   
 firestore 
 . 
  REGION_NAME 
 
 . 
 rep 
 . 
 googleapis 
 . 
 com 
 : 
 443 
 

  firestore 
 . 
  REGION_NAME 
 
 . 
 rep 
 . 
 googleapis 
 . 
 com 
 

   
 firestore 
 . 
  REGION_NAME 
 
 . 
 rep 
 . 
 googleapis 
 . 
 com 
 : 
 443 
 

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 ).

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

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

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

Limitations

• Regional and multi-regional endpoints don't support real-time listeners .

Locational Endpoints (Deprecated)

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

Cloud Firestore previously supported locational endpoints with the following format:

   
  REGION_NAME 
 
 - 
 firestore 
 . 
 googleapis 
 . 
 com 
 : 
 443 
 

   REGION_NAME 
 
 - 
 firestore 
 . 
 googleapis 
 . 
 com 
 

   
  REGION_NAME 
 
 - 
 firestore 
 . 
 googleapis 
 . 
 com 
 : 
 443 
 

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 Cloud 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 .