ip-lookup

The ip-lookup operator retrieves geolocation data of IP addresses using MaxMind’s GeoIP2 and GeoLite2 databases to enrich events with details such as city, continent, country, latitude, longitude, postal code, region, and time zone based on the provided IP address field. You can customize which fields to return, add prefixes, and their language.

You can display ip-lookup results in a Map chart.

Prerequisite​

The ip-lookup operator needs a .mmdb database file from MaxMind. You need to download the file from MaxMind and then create a lookup table with it. This file contains the geolocation data needed for IP address enrichment.

MaxMind’s GeoIP2 City, GeoIP2 Country, and GeoLite2 are supported. The GeoIP2 databases are a more accurate version of the free GeoLite2 City database.

To download the free GeoLite2 City database you need a free GeoLite2 account. For details, see MaxMind’s Accessing GeoLite2 Free Geolocation Data documentation.

Syntax​

Arguments​

• Scope: The events to search.
• OutputField: Field(s) to return from the lookup. By default, all available fields are returned.
  • city – for example, Georgetown
  • continent – for example, North America
  • continent_code – for example, NA
  • country – for example, United States
  • country_code – for example, US
  • lat – numeric latitude coordinate
  • lon – numeric longitude coordinate
  • postal – for example, 40324
  • region – for example, Kentucky
  • region_code – for example, KY
  • time_zone – for example, America/Los_Angeles
• Prefix: A prefix to add to the output fields. For example, if the prefix is set to ip_, output fields will be named ip_city ip_country, etc.
• Lang: Specifies the language for data retrieval. Defaults to en for English. Supports Brazilian Portuguese (pt-BR), English (en), French (fr), German (de), Japanese (ja), Russian (ru), Simplified Chinese (zh-CN), and Spanish (es).
• LookupTable: The lookup table filename that contains MaxMind’s GeoIP2 and GeoLite2 database. Do not add the .mmdb file extension. For example, a filename of GeoLite2-city.mmdb is entered as GeoLite2-city.
• IPField: The field name with an IP address. Defaults to ip.

Examples​

• Lookup geolocation data on the ip field.

  dataset=myDataset
  | ip-lookup 'GeoLite2-City'

  Copy
• Lookup geolocation data on the my_ip field.

  dataset=myDataset
  | ip-lookup 'GeoLite2-City' on my_ip

  Copy
• Lookup geolocation data on the ip_address field and return only the prefixed ip_lat and ip_lon fields.

  dataset=myDataset
  | ip-lookup output=lat,lon prefix=ip_ 'GeoLite2-City' on ip_address

  Copy
• Lookup geolocation data on the ip_address field and return only the city and region fields in Spanish.

  dataset=myDataset
  | ip-lookup output=city,region lang=es 'GeoIP2-City' on ip_address

  Copy