Modern applications generate enormous amounts of log and event data every second. Understanding where your users, visitors or network traffic originate is essential for analytics, cybersecurity, fraud prevention and business intelligence. The IP2Location Processor for Elasticsearch Ingest Pipeline makes it easy to enrich your documents with powerful IP geolocation data automatically during ingestion.
The IP2Location Processor is designed specifically for Elasticsearch Ingest Pipelines, enabling real-time geolocation lookups directly within your data processing workflow. By integrating this processor into your pipeline, you can automatically convert IP addresses into valuable geographic and network information before indexing documents into Elasticsearch.
Why Use the IP2Location Processor #
Traditional IP geolocation workflows often require external applications or post-processing scripts to enrich data. The IP2Location Processor simplifies this process by performing geolocation lookups natively during document ingestion. This approach improves efficiency, reduces architecture complexity and ensures your indexed data is immediately searchable with enriched location intelligence.
With the IP2Location Processor, Elasticsearch users can enrich logs, events, security alerts, web traffic records and application telemetry with detailed information such as country and region, city information, ISP and domain, latitude and longitude, ZIP code and time zone, ASN and CIDR details and many more. This enriched information can then be visualized in Kibana dashboards, used for threat detection or analyzed for business insights.
Flexible Processor Configuration #
The IP2Location Processor provides a flexible set of configuration options to fit various deployment requirements.
The required settings include:
field: Specifies the field containing the IP address for geolocation lookup.database_file: Defines the path to the IP2Location BIN database file.
Optional settings allow additional customization:
target_field: Stores lookup results in a custom field. The default is geo.ignore_missing: Prevents errors if the IP field does not exist.first_only: Returns only the first geolocation result when the IP field contains an array.fields: Lets users specify exactly which geolocation fields should be returned.
The fields option is especially useful for optimizing storage and performance by selecting only the data required by your application.
Supports Rich Geolocation Intelligence #
The processor supports a comprehensive range of lookup fields, including:
- country_code
- country_name
- region_name
- city_name
- isp
- latitude
- longitude
- asn
- as_domain
- usage_type
- category
- district
- mobile_brand
- net_speed
- and much more.
This extensive coverage makes the processor suitable for use cases ranging from cybersecurity monitoring to customer analytics and fraud detection.
Powered by IP2Location BIN Databases #
To use the processor, users must download an IP2Location BIN database file. The processor supports both free and commercial databases provided by IP2Location. Users can download the database files from:
- IP2Location LITE BIN data (Free)
- IP2Location Commercial BIN data (Commercial)
The LITE database offers free IP geolocation data for developers and testing environments, while the commercial databases provide higher accuracy and more detailed IP intelligence fields.
Processor Installation #
The IP2Location Processor must first be installed into your Elasticsearch environment before it can be used within ingest pipelines. The ZIP file can de downloaded from here. Once installed, restart the Elasticsearch service to activate the processor plugin.
/usr/share/elasticsearch/bin/elasticsearch-plugin install file://elasticsearch-ingest-ip2location.zipPipeline Creation #
After installation, create an Elasticsearch ingest pipeline that uses the IP2Location processor. The pipeline configuration defines the source IP field, BIN database location and optional output settings.
curl -X PUT "http://localhost:9200/_ingest/pipeline/ip2location" -H "Content-Type: application/json" -d '
{
"description" : "Pipeline for geolocation info using IP2Location processor",
"processors" : [
{
"ip2location": {
"field": "ip",
"target_field": "geo",
"database_file": "/usr/share/elasticsearch/plugins/ip2location/DB.BIN",
"fields": [
"country_code",
"country_name",
"region_name",
"city_name",
"location",
"isp",
"asn"
]
}
}
]
}'Document Insertion #
Once the pipeline has been created, documents containing IP addresses can be indexed through the ingest pipeline. During ingestion, the processor automatically enriches the documents with geolocation information.
curl -X PUT "http://localhost:9200/index-1/_doc/my_id?pipeline=ip2location" -H "Content-Type: application/json" -d '
{
"ip": "8.8.8.8"
}'Document Retrieval #
After documents are indexed, the enriched geolocation data can be retrieved directly from Elasticsearch. This enables location-aware analytics, dashboards and security investigations.
curl -X GET "http://localhost:9200/index-1/_doc/my_id" -H "Content-Type: application/json"Conclusion #
The IP2Location Processor provides a simple and efficient way to enrich Elasticsearch documents with valuable geolocation intelligence during ingestion. By integrating IP geolocation directly into ingest pipelines, users can improve analytics, security monitoring and operational visibility with minimal effort.
