Fetching a List of Available Locations
Locations represent a cluster of servers at a specific geographical location. The SDK will use proper caching so that this list is frequently updated.
get_locations_for_protocols
Fetch list of locations with an HTTP call or from local HTTP cache, small response payload size. This will return all available locations for the provided subscription id and protocols. A shortcut to this method is get_locations() which will set the protocols to lightway, openvpn and wireguard.
Parameters
| Name | Description |
|---|---|
| subscription_id | ID of the subscription which has a VPN entitlement. You can obtain that subscription id as described in Obtaining a VPN Subscription ID |
| protocols | An array of protocol identifiers. lightwayopenvpnwireguardproxy |
Returns
Array of ServerLocation objects if successful, InstanceDiscoveryException otherwise.
get_full_locations_for_protocols
Fetch full dataset of all locations and endpoints, around 3MB JSON payload compressed to around 300kb over the wire, or read from local cache. The method returns all available locations for the provided subscription id and protocols.
This method refreshes over the network once the cache expires, so it never returns stale data. The returned FullLocationsResult carries a cacheState flag indicating whether the dataset was freshly Fetched or served from a still-fresh Cached copy. A cached dataset is only reused for the subscription it was originally fetched for.
The set of protocols must be full list of protocols supported by current client.
Parameters
| Name | Description |
|---|---|
| subscription_id | ID of the subscription which has a VPN entitlement. You can obtain that subscription id as described in Obtaining a VPN Subscription ID |
| protocols | An array of all protocol identifiers supported by current client. lightwayopenvpnwireguardproxy |
Returns
FullLocationsResult upon success, InstanceDiscoveryException otherwise.
FullLocationsResult
| Name | Type | Description |
|---|---|---|
| locations | Array of ServerLocation | The locations matching the requested protocols |
| cacheState | CacheState | Fetched if retrieved over the network, Cached if served from a still-fresh cache |
CacheState
Indicates where a returned value came from, relative to the local cache.
| Value | Description |
|---|---|
| Fetched | Freshly fetched over the network (and the cache refreshed). Only from getFullLocationsForProtocols. |
| Cached | Served from cache while still within its freshness window. |
| Stale | Served from cache after its freshness window elapsed. Only from the cache-only accessors (getEndpointsForProtocols, getDnsIp). |
ServerLocation
| Name | Description |
|---|---|
| id | Unique ID of that location |
| name | Display Name of that location |
| latitude | Geographical Latitude of that location |
| longitude | Geographical Longitude of that location |
| country_code | ISO3166-1 alpha2 Country Code |
| instance_count_min | Minimum number of instances in that location |
| instance_count_max | Maximum number of instances in that location |
| is_geolocated | If true, this instance is physically not located in that location, but emulates the location by using a specific set of IPs, which are associated with that location |
| popularity_order | If set, it defines the popularity of that location, which can be used to show popular locations in the UI of the app |
| test_ips | A set of IPs, which this instance provided to run speedtests |