# 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:

```json
{
  "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:

```json
{
  "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