Geolocus

Description

The Geolocus.io enrichment enriches IP addresses with geolocation data from the Geolocus MMDB database. [https://www.geolocus.io/] It provides comprehensive location information including country, region, city, coordinates, timezone, ISP, organization, and ASN data for IP addresses.

Compatible with all Monad tiers

Prerequisites

None

Setup Instructions

1. Configure the join key path for IP addresses in your incoming records
2. Set the destination path for enriched data
3. Optionally configure the no-match response message

Configuration Options

Settings

Setting	Type	Required	Default	Description
ip_address_path	string	Yes	-	The JSON path to the IP address field in incoming records (e.g., "source.ip", "client_ip").
destination_path	string	Yes	-	The JSON path where geolocation data will be added to the record (e.g., "geolocus", "enrichment.geo").
no_match_response	string	No	"No geolocation data found"	Message returned when an IP address is not found in the database.

Secrets

None

Output Format

The enrichment adds geolocation data to an IP Address in a record data as JSON. For successful lookups, the output contains geolocation fields such as:

{
  "country": "US",
  "countryname": "United States", 
  "region": "CA",
  "regionname": "California",
  "cityname": "Mountain View",
  "latitude": "37.4056",
  "longitude": "-122.0775",
  "timezone": "America/Los_Angeles",
  "organization": "Google LLC",
  "asn": "AS15169",
  "continent": "NA",
  "continentname": "North America"
}

For IP addresses not found in the database or errors, a structured response is returned:

{
  "ip": "192.0.2.1",
  "message": "No geolocation data found",
  "code": "no_match"
}

Error Handling

• Invalid IP format: Returns structured error with code "invalid_ip"
• IP not in database: Returns structured response with code "no_match"
• Database lookup failure: Returns structured error with code "lookup_failed"
• Missing IP field: Record passed through unchanged

Use Cases

• Analytics enhancement: Add geographic context to user behavior data