Available Locations

The available locations endpoint helps you determine which regions are currently able to host your game image. This is particularly useful for:

• Finding the best location for a new game session
• Checking server availability in different regions
• Measuring latency to different hosting locations

Getting Available Locations

Endpoint

GET /available-location/{image}

Path Parameters

Parameter	Type	Required	Description
image	string	Yes	The ID of the game image you want to check locations for

Example Request

GET /available-location/my-game-server HTTP/1.1
Host: api.gameye.io
Authorization: Bearer YOUR_TOKEN_HERE

Success Response

On success, you’ll receive a 200 OK response with a list of available locations. Regions use standardized names for clearer geographic understanding:

{
  "locations": [
    {
      "id": "eu-west-1",
      "ips": [
        "203.0.113.42"
      ]
    },
    {
      "id": "eu-central-1",
      "ips": [
        "198.51.100.24"
      ]
    },
    {
      "id": "us-east-1",
      "ips": [
        "192.0.2.15"
      ]
    }
  ]
}

Error Responses

Status Code	Description
401	Unauthorized - Invalid bearer token
404	Not Found - Image not found or you’re not authorized to use it

Using Location Information

IP Addresses for Latency Testing

Each location in the response includes a pingable IP address that you can use to test network latency. These IPs accept ICMP ping messages, allowing you to determine which location will provide the best performance for your players.

Example: Ping Test

# Testing latency to EU West region
ping 203.0.113.42

# Testing latency to EU Central region
ping 198.51.100.24

Best Practices

Here are some recommended practices when working with location data:

1. Don’t Cache Location Data - The list of available locations may change, so it’s best to request fresh data when needed rather than caching it
2. Latency-Based Location Selection - Test latency to each location to determine the best one for your players
3. Fallback Locations - Have backup locations in case your preferred location is unavailable
4. Regular Availability Checks - If your application needs to create sessions frequently, periodically check location availability

Common Usage Patterns

Player-Optimized Location Selection

1. Retrieve the list of available locations
2. Test latency from your player’s location to each available location
3. Select the location with the lowest latency
4. Create a new session in that location

Geographic Distribution

If you have players from different regions:

1. Group players by geographic proximity
2. Find the best available location for each group
3. Create sessions in multiple locations to minimize latency for all players

Availability Monitoring

For applications that need high availability:

1. Regularly check which locations are available
2. If a previously available location becomes unavailable, redirect new sessions to alternative locations