> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/stages/iploc.md).

# 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`](/xql-command-reference-guide/readme/stages/comp.md), [`fields`](/xql-command-reference-guide/readme/stages/fields.md), [`filter`](/xql-command-reference-guide/readme/stages/filter.md), [`limit`](/xql-command-reference-guide/readme/stages/limit.md), [`view`](/xql-command-reference-guide/readme/stages/view.md)
* **Functions**: [`count`](/xql-command-reference-guide/readme/functions/count_with_windowcomp_stage.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/stages/iploc.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.