Skip to main content
All CollectionsUpstreams
Enhancing Requests with Geocoding Headers
Enhancing Requests with Geocoding Headers

Learn how to leverage geographical information in your custom domains by enabling automatic geocoding headers

Drago Crnjac avatar
Written by Drago Crnjac
Updated over a week ago

Overview

SaaS Custom Domains offers a powerful feature that adds geocoding information to the requests forwarded to your upstream servers. By enabling this feature, you can gain valuable insights about your users' locations, allowing for more personalized and location-aware services. This guide will walk you through the geocoding feature and its benefits.

Benefits of Enabling Geocoding

  1. Enhanced User Experience: Tailor content based on users' locations.

  2. Improved Analytics: Gain deeper insights into your user base's geographical distribution.

  3. Compliance Support: Assist in regional compliance and content restrictions where necessary.

  4. Targeted Marketing: Enable location-based marketing strategies.

Enabling Geocoding for Upstreams

Geocoding is enabled at the upstream level. When you enable geocoding for an upstream, all custom domains associated with that upstream will benefit from this feature.

To enable geocoding, simply edit your existing upstream or enable it when creating a new one — look for the Geocoding checkbox and activate it.

How Geocoding Works

When enabled, our system analyzes the IP address of incoming requests and adds several HTTP headers containing geographical information. These headers are then forwarded along with the original request to your upstream/origin server.

Geocoding Headers Explained

Here's a complete list of the headers that will be added to requests when geocoding is enabled:

  1. X-SaaS-GeoIp-Country-Code: The ISO 3166-1 alpha-2 country code (e.g., "US" for the United States).

  2. X-SaaS-GeoIp-Country-Name: The full name of the country (e.g., "United States").

  3. X-SaaS-GeoIp-City: The name of the city, if available.

  4. X-SaaS-GeoIp-Subdivision-1-Name: The name of the first-level subdivision (e.g., a state in the US).

  5. X-SaaS-GeoIp-Subdivision-1-Code: The code of the first-level subdivision (e.g., "CA" for California).

  6. X-SaaS-GeoIp-Subdivision-2-Name: The name of the second-level subdivision, if applicable.

  7. X-SaaS-GeoIp-Subdivision-2-Code: The code of the second-level subdivision, if applicable.

  8. X-SaaS-GeoIp-Postal-Code: The postal code or ZIP code of the location.

  9. X-SaaS-GeoIp-Country-Eu: Indicates whether the country is in the European Union ("1" for yes, "0" for no).

  10. X-SaaS-GeoIp-Continent-Code: The two-letter continent code (e.g., "NA" for North America).

  11. X-SaaS-GeoIp-Continent-Name: The full name of the continent.

Example: Request from Edinburgh, Scotland

To illustrate how these headers work in practice, let's look at an example of the geocoding headers that would be added to a request originating from Edinburgh, Scotland:

X-SaaS-GeoIp-Country-Code: GB
X-SaaS-GeoIp-Country-Name: United Kingdom
X-SaaS-GeoIp-City: Edinburgh
X-SaaS-GeoIp-Subdivision-1-Name: Scotland
X-SaaS-GeoIp-Subdivision-1-Code: SCT
X-SaaS-GeoIp-Subdivision-2-Name: City of Edinburgh
X-SaaS-GeoIp-Subdivision-2-Code: EDH
X-SaaS-GeoIp-Postal-Code: EH1
X-SaaS-GeoIp-Country-Eu: false
X-SaaS-GeoIp-Continent-Code: EU
X-SaaS-GeoIp-Continent-Name: Europe

In this example:

  • The country code is GB for Great Britain.

  • The first-level subdivision is Scotland, with its code SCT.

  • The second-level subdivision is the City of Edinburgh, with its code EDH.

  • The postal code EH1 represents the central area of Edinburgh.

  • The "Country-Eu" value is false because the UK is no longer part of the European Union.

This detailed geographical information allows you to create highly specific location-based features or content for your users. For instance, you could use this data to display local events in Edinburgh, show prices in British Pounds, or apply any Scotland-specific regulations to your service.

Using Geocoding Information

With these headers available in your requests, you can:

  • Implement location-based content delivery

  • Customize user experiences based on geographical data

  • Comply with regional regulations or restrictions

  • Analyze traffic patterns and user demographics

Privacy Considerations

While geocoding provides valuable data, it's important to use this information responsibly and in compliance with applicable privacy laws and regulations, such as GDPR for users in the European Union.

Accuracy Note

Please be aware that IP-based geolocation is not always 100% accurate, especially for users utilizing VPNs or other IP-masking technologies. Use this data as a helpful indicator rather than a definitive source of location information.

That's it! You now have the power of geocoding at your fingertips. Leverage this feature to create more dynamic, location-aware applications and services.

Until next time, keep building!

Need more help? Reach out via the Intercom chat widget and we'll be right with you!

Did this answer your question?