Custom Geographic Details


Instana maps end-user IP addresses to geographic details, e.g., city and country names. This is done by inspecting various HTTP headers to retrieve the end-user IP addresses. These IP addresses are then translated to geographic details with the help of Maxmind's geographic databases.

This page describes how to configure custom mapping rules from IP address ranges to geographic details. The main use case for these custom mapping rules are private networks. For example, when accessing (self-hosted) Instana installations through private networks. In such cases, public geographic databases will never contain relevant information and as such the translation process will provide either no results or only wrong/unhelpful results.

For self-hosted Instana installations, make sure that the configurations for end-user monitoring are completed.

Data Format

Rules for custom geographic details are always expressed through comma-separated values (CSV). This section describes the technical details of data format as required by both the user-interface and the Web REST API.

CSV Format

  • Column delimiter: ,
  • Quoting character: "
  • Record separator: \r\n
  • The first line must be a header record
  • Empty lines are allowed
  • Up to 512 rules

Supported columns

  • network (required): Either a single IPv4/IPv6 address or an IPv4/IPv6 address range expressed through CIDR notation. Example:
  • latitude: Latitude part of the geographic coordinates in decimal degrees. Example: 51.5900204
  • longitude: Longitude part of the geographic coordinates in decimal degrees. Example: 6.1974817
  • accuracy_radius: An estimation how accurate the coordinates are in kilometers around latitude/longitude. Example: 8
  • city_name: Name of the city. Example: Kevelaer
  • subdivision_1_name: Name of the least specific subdivision. Commonly used to express information about states. In case of countries containing countries this might also contain the name of contained countries, e.g., England is a country within the country United Kingdom. Example: North Rhine-Westphalia
  • subdivision_1_iso_code: Code representation of the subdivision 1. Example: NW
  • subdivision_2_name: A more specific subdivision than subdivision 1. Example: Kreis Kleve
  • subdivision_2_iso_code: Code representation of subdivision 2. Example: KLE
  • country_name: Name of the country. Example: Germany
  • country_iso_code: Code representation of the country. Example DE
  • continent_name: Name of the continent. Example: Europe
  • continent_code: Code representation of the continent. Example: EU


network,latitude,longitude,accuracy_radius,city_name,subdivision_1_name,subdivision_1_iso_code,subdivision_2_name,subdivision_2_iso_code,country_name,country_iso_code,continent_name,continent_code,51.5900204,6.1974817,8,Kevelaer,North Rhine-Westphalia,NW,Kreis Kleve,KLE,Germany,DE,Europe,EU

Configuration through the Web REST API

Get configuration

curl -H "Authorization: apiToken $API_TOKEN" \
  -H "Accept: text/csv" \

Set configuration

curl -X PUT \
  -H "Authorization: apiToken $API_TOKEN" \
  -H "Accept: text/csv, application/json" \
  -H "Content-Type: text/csv" \
  "https://$UNIT-$$WEBSITE_ID/geo-mapping-rules" \
  -d 'network,latitude,longitude,accuracy_radius,city_name,subdivision_1_name,subdivision_1_iso_code,subdivision_2_name,subdivision_2_iso_code,country_name,country_iso_code,continent_name,continent_code,51.5900204,6.1974817,8,Kevelaer,North Rhine-Westphalia,NW,Kreis Kleve,KLE,Germany,DE,Europe,EU'

Configuration through the user interface

The Instana user interface provides means to interact with the Web REST API. It supports downloads and uploads of the aforementioned CSV files for your convenience. The specific view can be found within a website's configuration tab under Custom Geographic Details.

Screenshot showing the custom geographic details view