The Locations API: Platform Saga Part IV

In this chapter, we'll learn about the Locations API that Turso provides to retrieve a list of locations you can host and replicate databases to. There's also a handy API to fetch the closest region.

Before you continue, make sure you've read the previous chapters in this series:

• The Organization API: Platform Saga Part 3
• The Authorization API: Platform Saga Part 2
• A Hero's API Journey Begins: Platform Saga Part 1

All databases have a primary location (region) where data is stored, and can't be changed.

Databases can be replicated to other regions closer to your users by adding more locations to the group your database belongs to — we'll learn about groups in the next chapter.

#List all Locations

Using the Turso Platform API we can fetch a list of locations from the API:

curl -L https://api.turso.tech/v1/locations \
  -H 'Authorization: Bearer TOKEN'

This returns a JSON object of all possible locations:

{
  "locations": {
    "ams": "Amsterdam, Netherlands",
    "arn": "Stockholm, Sweden",
    "atl": "Atlanta, Georgia (US)",
    "bog": "Bogotá, Colombia",
    "bom": "Mumbai, India",
    "bos": "Boston, Massachusetts (US)",
    "cdg": "Paris, France",
    "den": "Denver, Colorado (US)",
    "dfw": "Dallas, Texas (US)",
    "ewr": "Secaucus, NJ (US)",
    "eze": "Ezeiza, Argentina",
    "fra": "Frankfurt, Germany",
    "gdl": "Guadalajara, Mexico",
    "gig": "Rio de Janeiro, Brazil",
    "gru": "São Paulo, Brazil",
    "hkg": "Hong Kong, Hong Kong",
    "iad": "Ashburn, Virginia (US)",
    "jnb": "Johannesburg, South Africa",
    "lax": "Los Angeles, California (US)",
    "lhr": "London, United Kingdom",
    "mad": "Madrid, Spain",
    "mia": "Miami, Florida (US)",
    "nrt": "Tokyo, Japan",
    "ord": "Chicago, Illinois (US)",
    "otp": "Bucharest, Romania",
    "phx": "Phoenix, Arizona (US)",
    "qro": "Querétaro, Mexico",
    "scl": "Santiago, Chile",
    "sea": "Seattle, Washington (US)",
    "sin": "Singapore, Singapore",
    "sjc": "San Jose, California (US)",
    "syd": "Sydney, Australia",
    "waw": "Warsaw, Poland",
    "yul": "Montreal, Canada",
    "yyz": "Toronto, Canada"
  }
}

The three-digit code is what you'll often use to reference the location in the API. For example, when creating or managing group locations, you'll use the location code.

#Fetch closest location

This handy API (mostly used by the Turso CLI) allows you to fetch the closest location to a given IP address:

curl https://region.turso.io

The response looking something like this:

{
  "server": "lhr",
  "client": "lhr"
}

The server property is the closest location to the server, and the client property is the closest location to the client.

That's it! We now know how to retrieve a list of locations where databases can be created, and replicated to. We also know how to fetch the closest region.

#Working with locations

We can add and remove locations from groups to replicate data globally, and we'll learn about that in part 5.

Go to next chapter