iploc

Use the `iploc` stage to enrich event data by associating IPv4 addresses with predefined geolocation attributes. This capability is fundamental for security analysts to understand the geographic origin or destination of network activity within their environment.

## Syntax

```sql
iploc <field> [loc_field1 [as <alias1>], loc_field2 [as <alias2>], ...]
```

## Parameters

| Name | Type | Required | Description |
| ----------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `field` | string, integer | Yes | The input field containing the IPv4 address to be geolocated. |
| `loc_field` | string | No | Specific geolocation attributes to return (for example, `loc_country`, `loc_city`). If omitted, a default set is added. |
| `alias` | string | No | The alias name for the geolocation field, using the `as` clause. |

## Returns

The `iploc` stage returns the original event records enriched with additional columns containing geolocation information (such as `loc_country`, `loc_city`, `loc_latlon`, etc.) corresponding to the provided IPv4 address.

## Usage notes

* The `iploc` stage can only be used with fields that contain numbers or strings.
* Geolocation data generated by this stage can be visualized on a graph of `type = map`, where the x-axis is set to `loc_country` or `loc_latlon`, and the y-axis is a number field.
* **Optimization**: It is crucial to optimize queries for performance and cost. Apply `filter` stages _before_ `iploc` to reduce the dataset size, ensuring `iploc` only processes relevant records.
* **Optimization**: Use the `fields` stage early in your query to select only the necessary columns, minimizing the data processed by subsequent stages including `iploc`.

## Examples

### Example 1: Basic iploc (default geolocation fields)

**Goal**: Enrich the `ipv4_address` field with the default set of geolocation attributes.

**XQL code**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| limit 5
| iploc ipv4_address
```

**Explanation**: The query applies the `iploc` stage to the `ipv4_address` field. Since no specific output fields are defined, it returns the default geolocation columns. Note that for private IPs (RFC1918), the country is often identified as "Private" with NULL values for granular details.

**Output**:

| EVENT\_ID | IPV4\_ADDRESS | LOC\_COUNTRY | LOC\_CITY | LOC\_LATLON |
| --------- | -------------- | ------------ | --------- | ----------- |
| 101 | 192.168.1.10 | Private | NULL | NULL |
| 102 | 10.0.0.5 | Private | NULL | NULL |
| 103 | NULL | NULL | NULL | NULL |
| 104 | 172.31.255.255 | Private | NULL | NULL |
| 105 | 192.168.10.20 | Private | NULL | NULL |

### Example 2: Specifying selected geolocation fields

**Goal**: Enrich the `ipv4_address` field but return only the Country and City attributes.

**XQL code**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| limit 5
| iploc ipv4_address loc_country, loc_city
```

**Explanation**: The query uses `iploc` on `ipv4_address` but explicitly requests only the `loc_country` and `loc_city` columns to be added to the result set.

**Output**:

| EVENT\_ID | IPV4\_ADDRESS | LOC\_COUNTRY | LOC\_CITY |
| --------- | -------------- | ------------ | --------- |
| 101 | 192.168.1.10 | Private | NULL |
| 102 | 10.0.0.5 | Private | NULL |
| 103 | NULL | NULL | NULL |
| 104 | 172.31.255.255 | Private | NULL |
| 105 | 192.168.10.20 | Private | NULL |

### Example 3: Aliasing geolocation fields

**Goal**: Enrich the `ipv4_address` field with specific attributes and rename the output columns for clarity.

**XQL code**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| limit 5
| iploc ipv4_address loc_country as IP_Country, loc_latlon as IP_LatLon
```

**Explanation**: The query extracts `loc_country` and `loc_latlon` for the `ipv4_address`, renaming them to `IP_Country` and `IP_LatLon` respectively using the `as` clause.

**Output**:

| EVENT\_ID | IPV4\_ADDRESS | IP\_COUNTRY | IP\_LATLON |
| --------- | -------------- | ----------- | ---------- |
| 101 | 192.168.1.10 | Private | NULL |
| 102 | 10.0.0.5 | Private | NULL |
| 103 | NULL | NULL | NULL |
| 104 | 172.31.255.255 | Private | NULL |
| 105 | 192.168.10.20 | Private | NULL |

### Example 4: Viewing iploc results as a map graph

**Goal**: Combine `iploc` with aggregation to count IP addresses by country and visualize the data.

**XQL code**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| iploc ipv4_address loc_country as country
| filter country != null and ipv4_address != null
| comp count() as ip_count by country
| view graph type = map xaxis = country yaxis = ip_count
| limit 10
```

**Explanation**: The query enriches the data with `loc_country` (aliased as `country`), filters out nulls, and aggregates the count of IPs per country. The `view` stage then configures the output to be displayed as a map graph. The table output below represents the underlying data for the visualization.

**Output**:

| COUNTRY | IP\_COUNT |
| ------- | --------- |
| Private | 8 |
| NULL | 2 |

## Related articles

* **Stages**: [`comp`](comp), [`fields`](fields), [`filter`](filter), [`limit`](limit), [`view`](view)
* **Functions**: [`count`](../functions/count_with_windowcomp_stage)