Geolocation

IMPORTANT: GeoIP information, including data streamed by our log streaming service, is intended to be used only in connection with your internal use of Fastly services. Use of GeoIP data for other purposes may require permission of a GeoIP vendor, such as Digital Element.

Fastly provides a variety of geolocation data, allowing the originating geographical location of a request to be determined.

The client.geo. namespace contains the geolocation data we recommend for most use cases. The client.as. namespace offers information about the client's Autonomous System (AS), which is often the end user's Internet Service Provider.

NOTE: For backwards compatibility, we also support a legacy dataset with variables in the geoip. namespace. The data returned for a given IP address may be different between the current and legacy datasets, especially at the city level. While it's possible to migrate configurations by replacing the older geoip.* namespace with client.geo.*, we recommend you carefully review any business logic that may rely on this data, especially if it's implemented in VCL or if the values are exposed via HTTP headers or real-time streaming logs.

In particular, keep in mind the following:

Results for IPv6 addresses are only returned for client.geo. and client.as. namespaces.
The geolocation dataset versions each have different formatting conventions. For example, client.geo.city and client.geo.country_name exist as lowercase ASCII values whereas the values returned for the same fields in the geoip. namespace are mixed case.
The client.geo.region field contains ISO 3166-2 region codes but the geoip.region field contains FIPS10-4 region codes. The FIPS 10-4 standard was withdrawn in 2014.

Legacy	Current
`geoip.area_code`	`client.geo.area_code`
`geoip.city*`	`client.geo.city*`
`geoip.continent_code`	`client.geo.continent_code`
`geoip.country_code`	`client.geo.country_code`
`geoip.country_code3`	`client.geo.country_code3`
`geoip.country_name*`	`client.geo.country_name*`
`geoip.ip_override`	`client.geo.ip_override`
`geoip.latitude`	`client.geo.latitude`
`geoip.longitude`	`client.geo.longitude`
`geoip.metro_code`	`client.geo.metro_code`
`geoip.postal_code`	`client.geo.postal_code`
`geoip.region*`	`client.geo.region*`
`geoip.use_x_forwarded_for`	`client.geo.ip_override`

IP address used for lookup

The IP address used for the geolocation lookup is automatically populated from client.ip by default, but may be overridden explicitly by setting client.geo.ip_override.

Lossy formats

Geographic variables representing names are available in several formats. Note in particular the *.ascii variables are lossy. These variables have diacritics removed and are normalized to lower case spellings. These *.ascii variables are intended for ease of use as a symbolic string in code (for example, to perform some different action depending on the city name), and are generally inappropriate for presenting to users due to their simplified content.

Absent data

The data is updated periodically, as IP allocations change and various amendments are made. Some variables may be absent for the current data at any given time.

For STRING types, the special value ? is used to indicate absent data. These may be normalized to VCL empty strings using the if() ternary operator:

if (client.as.name == "?", client.as.name, "");

In general values of type STRING in VCL may be not set, but this should never occur for the Geolocation variables.

Reserved IP address blocks

The IPv4 and IPv6 address spaces have several blocks reserved for special uses; these include private use networks (e.g., 192.168.0.0/16), loopback (127.0.0.1/8), and address ranges reserved for documentation (e.g., 203.0.113.0/24 RFC 5737 TEST-NET-3).

Geographic data has no meaningful association for these ranges, and so the Geolocation VCL variables present special values for these ranges instead. These values are:

Variable	Value for reserved blocks
`client.as.number`	0
`client.as.name`	`?`
`client.geo.latitude`	0.000
`client.geo.longitude`	0.000
`client.geo.conn_speed`	`broadband`
`client.geo.metro_code`	-1
`client.geo.utc_offset`	9999
`client.geo.area_code`	0
`client.geo.postal_code`	0
`client.geo.continent_code`	`**`
`client.geo.country_code`	`**`
`client.geo.country_code3`	`***`
`client.geo.country_name`	`reserved/private`
`client.geo.city`	`reserved`
`client.geo.region`	`***`

AOL data in region and city geolocation elements

The third-party geolocation database that Fastly uses may return AOL for queried client.geo.region and client.geo.city variables, despite AOL not representing a region or city per the region code requirements stated in ISO 3166-2. AOL, an internet service provider, assigns dial-up users an internet access point based on the country in which their AOL account is established. This means that the IP addresses associated with their access to the internet don't necessarily reflect the country from which they are connecting.

On this page:

IP address used for lookup
Lossy formats
Absent data
Reserved IP address blocks
AOL data in region and city geolocation elements