geolocate

Documentation

Overview

geolocate exposes a function to obtain geographical coordinates for a given country. Previously, we used a City location database to obtain a country assignment for the request IP. This new approach moves in the direction of delegating the "country" or region geolocation to the client side (and let it override when needed), which greatly simplifies the responsibility of keeping a geodb up to date. The clients are also expected to pass a country code for background queries.

auto-generated code. Do NOT edit.

auto-generated code. Do NOT edit.

Index

• Constants
• Variables
• func ContinentCodeToLabel(i int) string
• func ContinentNameToInt(s string) int
• func CountryCodes() []string
• func Distance(from, to *Point) float64
• func DistanceBetweenCountries(cc string, to string) (float64, error)
• func DistanceFromCountry(cc string, to *Point) (float64, error)
• func GeolocateCities(target []string) map[string]Point
• func GetContinentForCountryCode(cc string) int
• func GetEstimatedLatencyBetweenCountries(lm *latency.Metric, from, to string) float64
• func GetNearestCountry(from string, countryCodes []string) (string, error)
• func GetRegionForCountryCode(cc string) int
• func IsValidCountryCode(cc string) bool
• func PickBestLocations(lm *latency.Metric, cc string, locations []*models.Location) []*models.Location
• func RegionFromLabel(s string) int
• func RegionToLabel(i int) string
• func SortLocationsByDistanceToCountry(cc string, locations []*models.Location) []*models.Location
• func SortLocationsByEstimatedLatencyToCountry(lm *latency.Metric, cc string, locations []*models.Location) []*models.Location
• type Country
• type Point
  • func GetCentroidForCountry(cc string) (*Point, error)

Constants

const (
	XX = iota // unknown
	AN        // antarctica
	AS        // asia
	AF        // africa
	EU        // europe
	NA        // north america
	SA        // south america
	OC        // oceania
)

const (
	UnknownRegion = iota
	North
	South
)

Variables

var ErrUnknownCountry = "unknown country code"

Functions

func ContinentCodeToLabel

func ContinentCodeToLabel(i int) string

func ContinentNameToInt

func ContinentNameToInt(s string) int

func CountryCodes

func CountryCodes() []string

func Distance

func Distance(from, to *Point) float64

Distance returns the great circle distance between two `Points`.

func DistanceBetweenCountries

func DistanceBetweenCountries(cc string, to string) (float64, error)

DistanceBetweenCountries expects two country codes, and it will return the great circle distance (in km) between the centroids for the two countries.

func DistanceFromCountry

func DistanceFromCountry(cc string, to *Point) (float64, error)

DistanceFromCountry returns the great circle distance between a target `Point` and a country (specified by country code).

func GeolocateCities

func GeolocateCities(target []string) map[string]Point

GeolocateCities receives an array of strings, and it returns a map[string]Point

func GetContinentForCountryCode

func GetContinentForCountryCode(cc string) int

func GetEstimatedLatencyBetweenCountries

func GetEstimatedLatencyBetweenCountries(lm *latency.Metric, from, to string) float64

GetEstimatedLatencyBetweenCountries will return an estimation of latency (in ms) derived from an empirical dataset. This can be used to correct naive distance calculations, and sort locations accordingly.

func GetNearestCountry

func GetNearestCountry(from string, countryCodes []string) (string, error)

GetNearestCountry receives an array of country codes, and returns the one that is nearest.

func GetRegionForCountryCode

func GetRegionForCountryCode(cc string) int

func IsValidCountryCode

func IsValidCountryCode(cc string) bool

func PickBestLocations

func PickBestLocations(lm *latency.Metric, cc string, locations []*models.Location) []*models.Location

PickBestLocations calls the two methods (distance, latency) and merges the results. Note: this method picks the union of the two calls, so it might actually return more than `maxLocations`. TODO: this method is a workaround to the fact that the latency calculation is very blurry since it takes the average of the whole country. TODO: this is a good place to add region preferences.

func RegionFromLabel

func RegionFromLabel(s string) int

func RegionToLabel

func RegionToLabel(i int) string

func SortLocationsByDistanceToCountry

func SortLocationsByDistanceToCountry(cc string, locations []*models.Location) []*models.Location

SortLocationsByDistanceToCountry return an array of locations sorted by "great circle distance" to the centroid of a given country. This is a very naive approach, but it's probably good enough for a small number of hand-picked locations like the Riseup provider uses right now.

You might also be interested in using SortLocationsByEstimatedLatency (see below), which uses an empirical model of a latency metric.

For the sake of fairness, and for providers with limited resources in terms of adding different locations, we might assign gateways to specific regions. The region and continent fields might be useful for these lookups.

func SortLocationsByEstimatedLatencyToCountry

func SortLocationsByEstimatedLatencyToCountry(
	lm *latency.Metric,
	cc string,
	locations []*models.Location) []*models.Location

TODO: work in progress. This is correctly sorting locations by latency to the AVERAGE latency to the country in which the location is in, but we might need to desaggregate the database. Problem is that we need the equivalent of cloud regions: sort by proximity to US-west, AS-east etc.

Types

type Country

type Country struct {
	Region    string
	Continent string
}

type Point

type Point struct {
	Lat float64
	Lon float64
}

func GetCentroidForCountry

func GetCentroidForCountry(cc string) (*Point, error)

GetCentroidForCountry returns a *Point for the given country, and an error if the lookup was not successful.