IPGeolocation.io CLI Tool

Overview

The official ipgeolocation Command Line Interface (CLI) provides a fast, lightweight, and script-friendly way to access IPGeolocation.io's set of APIs directly from your terminal. It lets developers, DevOps engineers, network operators, and security teams retrieve IP intelligence without writing code or handling raw HTTP requests.

Using a single executable, you can query IP location, security intelligence, ASN details, timezone, astronomy, abuse contact information, and user agent parsing for your own IP or for any IPv4, IPv6 address, or domain name. The CLI outputs structured, machine-readable data that integrates seamlessly into shell scripts, cron jobs, CI/CD pipelines, monitoring systems, and log-processing workflows.

IP Geolocation API: Get all-in-one unified solution for location (city, locality, state, country, accuracy-radius, confidence etc.), currency, ASN (AS number, ASN name, organization, asn type, date of allocation, routes, upstreams, downstreams, peers), company (company/ISP name, company type, company domain), timezone, user agent string parsing, security (threat_score, is_tor, is_bot, proxy_provider_names, cloud_provider_name, relay_provider_name, vpn_provider_names, is_proxy, is_relay, is_vpn), and abuse contact (route/CIDR network, country, address, email, phone numbers) information.
IP Security API: Get security intelligence (threat score, VPN, proxy, Tor, relay, bot, and cloud-provider detection) for an IP address.
ASN API: Get ASN details along with peers, upstreams, downstreams, routes, and raw WHOIS.
Abuse Contact API: Get abuse emails, phone numbers, kind, organization, route/CIDR network and country.
Astronomy API: Get sunrise, sunset, moonrise, moonset, moon phases with precise twilight period times in combination with location information.
Time Zone API: Get timezone name, multiple time formats, daylight saving status and its details along with location information.
Timezone Convert API: Convert time between timezone names, geo coordinates, location addresses, IATA codes, ICAO codes, or UN/LOCODE.
User Agent API: Parse one or more user-agent strings to get browser, operating system, and device details.

The ipgeolocation CLI is built for speed and automation, making it easy to integrate IP intelligence into shell scripts, bash pipelines, cron jobs, and CI/CD workflows. It enriches server logs, firewall events, and SIEM data, supports on-the-fly lookups during incident response, and enables automated fraud detection, geo-based routing, and access control without language-specific dependencies. Designed for system administrators, DevOps engineers, and developers, the CLI delivers consistent, reliable insights directly in the terminal.

Based on:

API version: 3.0.0

Official Release:

Available on pkg.go.dev and GitHub Releases
Source Code: GitHub Repository

Requirements

Go 1.26.10 or Go 1.27.3, or a newer patched stable version (only for building from source)
API Key from IPGeolocation.io

Installation

1. Go install

To install ipgeolocation using go install, run:

go install github.com/IPGeolocation/cli/v2/cmd/ipgeolocation@latest

Make sure $GOBIN or $GOPATH/bin is in your PATH, then run:

ipgeolocation --help

2. Download and build from source

git clone https://github.com/IPGeolocation/cli.git
cd cli
go build -o ipgeolocation ./cmd/ipgeolocation
./ipgeolocation --help

Here, you will need to add $GOBIN or $GOPATH/bin to your PATH as well.

To build release archives for all supported platforms, install govulncheck and run:

go install golang.org/x/vuln/cmd/govulncheck@v1.9.0
bash build-release.sh

The script runs tests, checks the source and each binary, and writes archives and SHA256SUMS to dist/. Tagged releases run the same checks before publishing.

For local HTTPS regression checks, install Node.js and Postman CLI 1.73.0, then run node scripts/test-http.cjs.

3. Download Prebuilt Binaries

I. Overview

These are prebuilt binaries for the IPGeolocation.io CLI tool, version 2.1.1. Users can download these files directly from GitHub Releases or from the table below without needing to build from source.

The CLI provides geolocation information, timezone, user-agent parsing, bulk IP lookups, and more.

II. Prebuilt Binaries

Platform	Architecture	File Name / Download Link
Linux	amd64	ipgeolocation-2.1.1-linux-amd64.tar.gz
Linux	arm64	ipgeolocation-2.1.1-linux-arm64.tar.gz
macOS	amd64	ipgeolocation-2.1.1-darwin-amd64.tar.gz
macOS	arm64	ipgeolocation-2.1.1-darwin-arm64.tar.gz
Windows	amd64	ipgeolocation-2.1.1-windows-amd64.zip

Archives include SHA256SUMS for download verification.

III. Installation Instructions

Linux:

Download the .tar.gz file for your architecture.

Extract it to a folder in your PATH, e.g., /usr/local/bin:

tar -xzf ipgeolocation-2.1.1-linux-amd64.tar.gz -C /usr/local/bin

Rename the binary for simplicity:

mv /usr/local/bin/ipgeolocation-2.1.1-linux-amd64 /usr/local/bin/ipgeolocation

Make the binary executable:

chmod +x /usr/local/bin/ipgeolocation

Verify installation:

ipgeolocation --help

macOS:

Download the .tar.gz file for your architecture (amd64 or arm64).

Extract to a folder in your PATH, e.g., /usr/local/bin:

tar -xzf ipgeolocation-2.1.1-darwin-amd64.tar.gz -C /usr/local/bin

Rename the binary:

mv /usr/local/bin/ipgeolocation-2.1.1-darwin-amd64 /usr/local/bin/ipgeolocation

Make executable:

chmod +x /usr/local/bin/ipgeolocation

Verify installation:

ipgeolocation --help

Windows:

Download the .zip file.

Extract the ipgeolocation-2.1.1-windows-amd64.exe to a folder included in your system PATH.

Rename the binary to ipgeolocation.exe for convenience.

Open Command Prompt and verify:

ipgeolocation --help

4. Troubleshooting

Command not found: Ensure the binary is in a folder included in your PATH.
Execution permission error: Run chmod +x <binary> on Linux/macOS.
Wrong architecture: Download the binary matching your OS and CPU architecture.
Go install issues: Use GOPROXY=direct if Go module proxy caching creates issues.

APIs Documentation

The documentation below corresponds to the available APIs:

For a detailed comparison of what each plan offers, visit the Pricing Page.

Fields and commands Availability

IPGeolocation.io offers a free Developer plan and paid plans. The availability of each command across plans is presented below.

Sub Command	Details	Free	Paid
`config`	Set up and check API Key.
`my-ip`	Get the public IP address of the machine running the command. Does not require an API key.
`ipgeo`	Get geolocation data for a single IP address, along with network, currency, abuse, timezone, security, asn, user-agent, etc.
`bulk-ip-geo`	Get geolocation data for multiple IP addresses in a single API request, along with the same data as in `ipgeo`.
`ip-security`	Get security intelligence (threat score, VPN, proxy, Tor, relay, bot, and cloud-provider detection) for an IP address.
`bulk-ip-security`	Get security threat intelligence for multiple IP addresses, along with the same data as in `ip-security`.
`asn`	Get details of any AS number or IP address associated with an ASN.
`abuse`	Get abuse reporting contact information for a given IP address.
`astronomy`	Get sunrise, sunset, moonrise, moonset, and related data for a location.
`astronomy-timeseries`	Get astronomy information for a given date range at once.
`timezone`	Get timezone details using IP address, city, coordinates, IATA, ICAO, UNLOCODE, or timezone ID.
`time-conversion`	Convert time between two specified timezones using city, coordinates, IATA, ICAO, UNLOCODE, or timezone ID.
`parse-user-agent`	Parse a single user-agent string.
`parse-bulk-user-agents`	Parse multiple user-agent strings at once.

Authentication Setup

To authenticate API requests, you need to get an API key from IPGeolocation.io.

1. How to Get Your API Key

Sign up here: https://app.ipgeolocation.io/signup
(optional) Verify your email if you signed up using email.
Log in to your account: https://app.ipgeolocation.io/login
After logging in, navigate to your Dashboard to find your API key: https://app.ipgeolocation.io/dashboard

2. ApiKeyAuth

Once you've obtained the api key, configure your API client as follows:

The client must configure the authentication and authorization parameters in accordance with the API server security policy.

ipgeolocation config --apikey=<your-key>

Global Flags

These flags are available for all commands:

Flag	Description
`-h, --help`	Show help for the command.

ipgeolocation --version

Commands

1. config Command

Configure your API key for IPGeolocation.io.

I. config Usage

ipgeolocation config --apikey=<your-key>

II. Flags for config

Flag	Type	Description
`--apikey`	string	Your API key from IPGeolocation.io.

2. my-ip Command

Get the public IP address of the machine running the command, as seen by the ipgeolocation.io API.

I. my-ip Usage

ipgeolocation my-ip [flags]

II. Flags for my-ip

Flag	Type	Default	Description
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`, `text`.

III. Get your public IP address

ipgeolocation my-ip

Sample output:

Response Preview

1{
2  "ip": "203.0.113.24"
3}

Print only the IP address, which is useful in shell scripts:

MY_IP=$(ipgeolocation my-ip --output text)

echo "$MY_IP"

Sample output:

Response Preview

1203.0.113.24

3. ipgeo Command

Look up geolocation information for a single IP address or domain from the ipgeolocation.io API.

I. ipgeo Usage

ipgeolocation ipgeo [flags]

II. Flags for ipgeo

Flag	Type	Default	Description
`--ip`	string	`""`	IPv4, IPv6, or domain name (e.g. `8.8.8.8`, `google.com`).
`--include`	string[]	`[]`	Include extra fields (e.g. `hostname,geo_accuracy,dma_code,security,abuse,user_agent`).
`--fields`	string[]	`[]`	Return only specific fields (e.g. `location,asn.organization`).
`--exclude`	string[]	`[]`	Exclude fields from output. `--excludes` is also accepted.
`--lang`	string	`""`	Response language.
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

III. Free Plan Examples

Get info about your current IP:

ipgeolocation ipgeo

i. Get Default Fields in Free Plan

Look up a specific IP:

ipgeolocation ipgeo --ip 8.8.8.8

Sample output:

Response Preview

1{
2  "ip": "8.8.8.8",
3  "asn": {
4    "as_number": "AS15169",
5    "country": "US",
6    "organization": "Google LLC"
7  },
8  "country_metadata": {
9    "calling_code": "+1",
10    "languages": [
11      "en-US",
12      "es-US",
13      "haw",
14      "fr"
15    ],
16    "tld": ".us"
17  },
18  "currency": {
19    "code": "USD",
20    "name": "US Dollar",
21    "symbol": "$"
22  },
23  "location": {
24    "city": "Mountain View",
25    "continent_code": "NA",
26    "continent_name": "North America",
27    "country_capital": "Washington, D.C.",
28    "country_code2": "US",
29    "country_code3": "USA",
30    "country_emoji": "🇺🇸",
31    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
32    "country_name": "United States",
33    "country_name_official": "United States of America",
34    "district": "Santa Clara",
35    "geoname_id": "6301403",
36    "is_eu": false,
37    "latitude": "37.42240",
38    "longitude": "-122.08421",
39    "state_code": "US-CA",
40    "state_prov": "California",
41    "zipcode": "94043-1351"
42  },
43  "time_zone": {
44    "current_time": "2026-03-03 03:01:15.329-0800",
45    "current_time_unix": 1772535675.329,
46    "current_tz_abbreviation": "PST",
47    "current_tz_full_name": "Pacific Standard Time",
48    "dst_end": {
49      "date_time_after": "2026-11-01 TIME 01:00",
50      "date_time_before": "2026-11-01 TIME 02:00",
51      "duration": "-1.00H",
52      "gap": false,
53      "overlap": true,
54      "utc_time": "2026-11-01 TIME 09:00"
55    },
56    "dst_exists": true,
57    "dst_savings": 0,
58    "dst_start": {
59      "date_time_after": "2026-03-08 TIME 03:00",
60      "date_time_before": "2026-03-08 TIME 02:00",
61      "duration": "+1.00H",
62      "gap": true,
63      "overlap": false,
64      "utc_time": "2026-03-08 TIME 10:00"
65    },
66    "dst_tz_abbreviation": "PDT",
67    "dst_tz_full_name": "Pacific Daylight Time",
68    "is_dst": false,
69    "name": "America/Los_Angeles",
70    "offset": -8,
71    "offset_with_dst": -8,
72    "standard_tz_abbreviation": "PST",
73    "standard_tz_full_name": "Pacific Standard Time"
74  }
75}

Filtering response with the use of --fields and --exclude:

ipgeolocation ipgeo --ip 8.8.8.8 --fields=location --exclude location.continent_code,location.continent_name

Sample output:

Response Preview

1{
2  "ip": "8.8.8.8",
3  "location": {
4    "city": "Mountain View",
5    "country_capital": "Washington, D.C.",
6    "country_code2": "US",
7    "country_code3": "USA",
8    "country_emoji": "🇺🇸",
9    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
10    "country_name": "United States",
11    "country_name_official": "United States of America",
12    "district": "Santa Clara",
13    "geoname_id": "6301403",
14    "is_eu": false,
15    "latitude": "37.42240",
16    "longitude": "-122.08421",
17    "state_code": "US-CA",
18    "state_prov": "California",
19    "zipcode": "94043-1351"
20  }
21}

IV. Paid Plan Examples

i. Get Default Fields in Paid Plan

Look up a domain name with default fields

ipgeolocation ipgeo --ip google.com

Sample output:

Response Preview

1{
2  "asn": {
3    "as_number": "AS15169",
4    "country": "US",
5    "date_allocated": "2000-03-30",
6    "domain": "google.com",
7    "organization": "Google LLC",
8    "rir": "ARIN",
9    "type": "BUSINESS"
10  },
11  "company": {
12    "domain": "google.com",
13    "name": "Google LLC",
14    "type": "HOSTING"
15  },
16  "country_metadata": {
17    "calling_code": "+65",
18    "languages": [
19      "cmn",
20      "en-SG",
21      "ms-SG",
22      "ta-SG",
23      "zh-SG"
24    ],
25    "tld": ".sg"
26  },
27  "currency": {
28    "code": "SGD",
29    "name": "Singapore Dollar",
30    "symbol": "S$"
31  },
32  "domain": "google.com",
33  "ip": "142.250.4.100",
34  "location": {
35    "city": "Singapore",
36    "continent_code": "AS",
37    "continent_name": "Asia",
38    "country_capital": "Singapore",
39    "country_code2": "SG",
40    "country_code3": "SGP",
41    "country_emoji": "🇸🇬",
42    "country_flag": "https://ipgeolocation.io/static/flags/sg_64.png",
43    "country_name": "Singapore",
44    "country_name_official": "Republic of Singapore",
45    "district": "Singapore",
46    "geoname_id": "6951474",
47    "is_eu": false,
48    "latitude": "1.29041",
49    "longitude": "103.85211",
50    "state_code": "SG-01",
51    "state_prov": "Central Singapore Community Development Council",
52    "zipcode": "17"
53  },
54  "network": {
55    "connection_type": "",
56    "is_anycast": false,
57    "route": "142.250.4.0/24"
58  },
59  "time_zone": {
60    "current_time": "2026-03-03 19:03:29.994+0800",
61    "current_time_unix": 1772535809.994,
62    "current_tz_abbreviation": "SGT",
63    "current_tz_full_name": "Singapore Standard Time",
64    "dst_end": {},
65    "dst_exists": false,
66    "dst_savings": 0,
67    "dst_start": {},
68    "dst_tz_abbreviation": "",
69    "dst_tz_full_name": "",
70    "is_dst": false,
71    "name": "Asia/Singapore",
72    "offset": 8,
73    "offset_with_dst": 8,
74    "standard_tz_abbreviation": "SGT",
75    "standard_tz_full_name": "Singapore Standard Time"
76  }
77}

ii. Retrieving Geolocation Data in Multiple Languages

Here is an example to get the geolocation data for IP address '2001:4230:4890::1' in French fr language:

ipgeolocation ipgeo --ip 2001:4230:4890::1 --lang fr

Sample output:

Response Preview

1{
2  "asn": {
3    "as_number": "AS0",
4    "country": "",
5    "date_allocated": "",
6    "domain": "",
7    "organization": "",
8    "rir": "",
9    "type": ""
10  },
11  "company": {
12    "domain": "afrinic.net",
13    "name": "African Network Information Center AfriNIC Ltd",
14    "type": "BUSINESS"
15  },
16  "country_metadata": {
17    "calling_code": "+230",
18    "languages": [
19      "en-MU",
20      "bho",
21      "fr"
22    ],
23    "tld": ".mu"
24  },
25  "currency": {
26    "code": "MUR",
27    "name": "Mauritius Rupee",
28    "symbol": "₨"
29  },
30  "ip": "2001:4230:4890:0:0:0:0:1",
31  "location": {
32    "city": "Quatre Bornes",
33    "continent_code": "AF",
34    "continent_name": "Afrique",
35    "country_capital": "Port Louis",
36    "country_code2": "MU",
37    "country_code3": "MUS",
38    "country_emoji": "🇲🇺",
39    "country_flag": "https://ipgeolocation.io/static/flags/mu_64.png",
40    "country_name": "Maurice",
41    "country_name_official": "",
42    "district": "Quatre Bornes",
43    "geoname_id": "1106777",
44    "is_eu": false,
45    "latitude": "-20.24304",
46    "longitude": "57.49631",
47    "state_code": "MU-PW",
48    "state_prov": "Wilhems des plaines",
49    "zipcode": "72201"
50  },
51  "network": {
52    "connection_type": "",
53    "is_anycast": false,
54    "route": ""
55  },
56  "time_zone": {
57    "current_time": "2026-03-03 15:04:29.479+0400",
58    "current_time_unix": 1772535869.479,
59    "current_tz_abbreviation": "MUT",
60    "current_tz_full_name": "Mauritius Standard Time",
61    "dst_end": {},
62    "dst_exists": false,
63    "dst_savings": 0,
64    "dst_start": {},
65    "dst_tz_abbreviation": "",
66    "dst_tz_full_name": "",
67    "is_dst": false,
68    "name": "Indian/Mauritius",
69    "offset": 4,
70    "offset_with_dst": 4,
71    "standard_tz_abbreviation": "MUT",
72    "standard_tz_full_name": "Mauritius Standard Time"
73  }
74}

iii. Include HostName and User-Agent

ipgeolocation ipgeo --ip 219.100.37.207 --include hostname,user_agent

Sample output:

Response Preview

1{
2  "asn": {
3    "as_number": "AS36599",
4    "country": "US",
5    "date_allocated": "2017-01-25",
6    "domain": "rt.open.ad.jp",
7    "organization": "SoftEther Telecommunication Research Institute, LLC",
8    "rir": "ARIN",
9    "type": "ISP"
10  },
11  "company": {
12    "domain": "softether.co.jp",
13    "name": "SoftEther Corporation",
14    "type": "BUSINESS"
15  },
16  "country_metadata": {
17    "calling_code": "+81",
18    "languages": [
19      "ja"
20    ],
21    "tld": ".jp"
22  },
23  "currency": {
24    "code": "JPY",
25    "name": "Yen",
26    "symbol": "¥"
27  },
28  "hostname": "public-vpn-13-15.vpngate.v4.open.ad.jp",
29  "ip": "219.100.37.207",
30  "location": {
31    "city": "Tokyo",
32    "continent_code": "AS",
33    "continent_name": "Asia",
34    "country_capital": "Tokyo",
35    "country_code2": "JP",
36    "country_code3": "JPN",
37    "country_emoji": "🇯🇵",
38    "country_flag": "https://ipgeolocation.io/static/flags/jp_64.png",
39    "country_name": "Japan",
40    "country_name_official": "Japan",
41    "district": "Koto",
42    "geoname_id": "12149683",
43    "is_eu": false,
44    "latitude": "35.68467",
45    "longitude": "139.80881",
46    "state_code": "JP-13",
47    "state_prov": "Tokyo Metropolis",
48    "zipcode": "135-0022"
49  },
50  "network": {
51    "connection_type": "",
52    "is_anycast": false,
53    "route": "219.100.37.0/24"
54  },
55  "time_zone": {
56    "current_time": "2026-03-03 20:05:37.058+0900",
57    "current_time_unix": 1772535937.058,
58    "current_tz_abbreviation": "JST",
59    "current_tz_full_name": "Japan Standard Time",
60    "dst_end": {},
61    "dst_exists": false,
62    "dst_savings": 0,
63    "dst_start": {},
64    "dst_tz_abbreviation": "",
65    "dst_tz_full_name": "",
66    "is_dst": false,
67    "name": "Asia/Tokyo",
68    "offset": 9,
69    "offset_with_dst": 9,
70    "standard_tz_abbreviation": "JST",
71    "standard_tz_full_name": "Japan Standard Time"
72  },
73  "user_agent": {
74    "device": {
75      "brand": "GO",
76      "cpu": "Unknown",
77      "name": "GO Http Client",
78      "type": "Robot"
79    },
80    "engine": {
81      "name": "Go-http-client",
82      "type": "Robot",
83      "version": "2.0",
84      "version_major": "2"
85    },
86    "name": "Go-http-client",
87    "operating_system": {
88      "build": "??",
89      "name": "Cloud",
90      "type": "Cloud",
91      "version": "??",
92      "version_major": "??"
93    },
94    "type": "Robot",
95    "user_agent_string": "Go-http-client/2.0",
96    "version": "2.0",
97    "version_major": "2"
98  }
99}

iv. Include DMA, Abuse and Security

ipgeolocation ipgeo --ip 8.8.8.8 --include dma_code,abuse,security

Sample output:

Response Preview

1{
2  "abuse": {
3    "address": "1600 Amphitheatre Parkway\nMountain View\nCA\n94043\nUnited States",
4    "country": "",
5    "emails": [
6      "network-abuse@google.com"
7    ],
8    "kind": "group",
9    "name": "Abuse",
10    "organization": "Abuse",
11    "phone_numbers": [
12      "+1-650-253-0000"
13    ],
14    "route": "8.8.8.0/24"
15  },
16  "asn": {
17    "as_number": "AS15169",
18    "country": "US",
19    "date_allocated": "2000-03-30",
20    "domain": "google.com",
21    "organization": "Google LLC",
22    "rir": "ARIN",
23    "type": "BUSINESS"
24  },
25  "company": {
26    "domain": "google.com",
27    "name": "Google LLC",
28    "type": "HOSTING"
29  },
30  "country_metadata": {
31    "calling_code": "+1",
32    "languages": [
33      "en-US",
34      "es-US",
35      "haw",
36      "fr"
37    ],
38    "tld": ".us"
39  },
40  "currency": {
41    "code": "USD",
42    "name": "US Dollar",
43    "symbol": "$"
44  },
45  "ip": "8.8.8.8",
46  "location": {
47    "city": "Mountain View",
48    "continent_code": "NA",
49    "continent_name": "North America",
50    "country_capital": "Washington, D.C.",
51    "country_code2": "US",
52    "country_code3": "USA",
53    "country_emoji": "🇺🇸",
54    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
55    "country_name": "United States",
56    "country_name_official": "United States of America",
57    "district": "Santa Clara",
58    "dma_code": "807",
59    "geoname_id": "6301403",
60    "is_eu": false,
61    "latitude": "37.42240",
62    "longitude": "-122.08421",
63    "state_code": "US-CA",
64    "state_prov": "California",
65    "zipcode": "94043-1351"
66  },
67  "network": {
68    "connection_type": "",
69    "is_anycast": true,
70    "route": "8.8.8.0/24"
71  },
72  "security": {
73    "cloud_provider_name": "",
74    "is_anonymous": false,
75    "is_bot": false,
76    "is_cloud_provider": false,
77    "is_known_attacker": false,
78    "is_proxy": false,
79    "is_relay": false,
80    "is_residential_proxy": false,
81    "is_spam": false,
82    "is_tor": false,
83    "is_vpn": false,
84    "proxy_confidence_score": 0,
85    "proxy_last_seen": "",
86    "proxy_provider_names": [],
87    "relay_provider_name": "",
88    "threat_score": 0,
89    "vpn_confidence_score": 0,
90    "vpn_last_seen": "",
91    "vpn_provider_names": []
92  },
93  "time_zone": {
94    "current_time": "2026-03-03 03:06:38.417-0800",
95    "current_time_unix": 1772535998.417,
96    "current_tz_abbreviation": "PST",
97    "current_tz_full_name": "Pacific Standard Time",
98    "dst_end": {
99      "date_time_after": "2026-11-01 TIME 01:00",
100      "date_time_before": "2026-11-01 TIME 02:00",
101      "duration": "-1.00H",
102      "gap": false,
103      "overlap": true,
104      "utc_time": "2026-11-01 TIME 09:00"
105    },
106    "dst_exists": true,
107    "dst_savings": 0,
108    "dst_start": {
109      "date_time_after": "2026-03-08 TIME 03:00",
110      "date_time_before": "2026-03-08 TIME 02:00",
111      "duration": "+1.00H",
112      "gap": true,
113      "overlap": false,
114      "utc_time": "2026-03-08 TIME 10:00"
115    },
116    "dst_tz_abbreviation": "PDT",
117    "dst_tz_full_name": "Pacific Daylight Time",
118    "is_dst": false,
119    "name": "America/Los_Angeles",
120    "offset": -8,
121    "offset_with_dst": -8,
122    "standard_tz_abbreviation": "PST",
123    "standard_tz_full_name": "Pacific Standard Time"
124  }
125}

v. Get only specific fields in YAML:

ipgeolocation ipgeo --ip 1.1.1.1 --fields location --include dma_code,geo_accuracy --output yaml

Sample response:

Response Preview

1ip: 1.1.1.1
2location:
3    accuracy_radius: "27.276"
4    city: South Brisbane
5    confidence: low
6    continent_code: OC
7    continent_name: Oceania
8    country_capital: Canberra
9    country_code2: AU
10    country_code3: AUS
11    country_emoji: "\U0001F1E6\U0001F1FA"
12    country_flag: https://ipgeolocation.io/static/flags/au_64.png
13    country_name: Australia
14    country_name_official: Commonwealth of Australia
15    district: Brisbane
16    dma_code: ""
17    geoname_id: "10113228"
18    is_eu: false
19    latitude: "-27.47306"
20    locality: South Brisbane
21    longitude: "153.01421"
22    state_code: AU-QLD
23    state_prov: Queensland
24    zipcode: "4101"

Similarly, raw, table and pretty formats are also available. Or one can parse the simple response with | jq.

4. bulk-ip-geo Command

Look up geolocation information for multiple IP addresses in one request.

I. bulk-ip-geo Usage

ipgeolocation bulk-ip-geo [flags]

II. Flags for bulk-ip-geo

Flag	Type	Default	Description
`--ips`	string[]	`[]`	Comma-separated list of IPs. Example: `--ips 8.8.8.8,1.1.1.1`
`--file`	string	`""`	Path to a text file containing IPs (one per line).
`--include`	string[]	`[]`	Include modules not returned by default (e.g. `security,abuse`).
`--exclude`	string[]	`[]`	Exclude fields (e.g. `currency`).
`--fields`	string[]	`[]`	Return only specific fields (e.g. `location,time_zone`).
`--lang`	string	`""`	Response language (if supported).
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.
`--output-file`	string	`""`	Save output to JSON file. Example: `--output-file results`

For further information, please visit IP Geolocation API Documentation.

Look up 3 IP addresses:

ipgeolocation bulk-ip-geo --ips 8.8.8.8,1.1.1.1,192.30.253.112

Look up from a file:

ipgeolocation bulk-ip-geo --file=ips.txt --output-file results

Results will be written to the results.json file.

Output as YAML:

ipgeolocation bulk-ip-geo --ips=8.8.8.8 --output=yaml

Save results to JSON file:

ipgeolocation bulk-ip-geo --ips=8.8.8.8,1.1.1.1 --output-file=output.json

III. Output Formats

pretty (default): Human-readable formatted JSON.
raw: Raw API response.
table: Tabular display of common fields.
yaml: YAML-formatted output.
json file: If --output-file is provided, results are saved to a .json file.

5. ip-security Command

Look up IP security information using the ipgeolocation.io API.

I. ip-security Usage

ipgeolocation ip-security [flags]

II. Flags for ip-security

Flag	Type	Default	Description
`--ip`	string	`""`	IPv4 or IPv6 address.
`--exclude`	string[]	`[]`	Exclude fields from output.
`--fields`	string[]	`[]`	Return only specific fields (e.g. `security.threat_score`).
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

III. Get Default Fields in ip-security

Get info about your current IP:

ipgeolocation ip-security

Look up a specific IP:

ipgeolocation ip-security --ip 2.56.188.34

Sample output:

Response Preview

1
2{
3  "ip": "2.56.188.34",
4  "security": {
5    "bot_confidence_score": 0,
6    "bot_last_seen": "",
7    "bot_operator_name": "",
8    "bot_type": "",
9    "cloud_provider_name": "Clouvider Limited",
10    "corporate_gateway_provider_name": "",
11    "corporate_gateway_type": "",
12    "is_anonymous": true,
13    "is_bot": false,
14    "is_cloud_provider": true,
15    "is_corporate_gateway": false,
16    "is_known_attacker": true,
17    "is_known_good_bot": false,
18    "is_proxy": false,
19    "is_relay": false,
20    "is_residential_proxy": false,
21    "is_spam": false,
22    "is_tor": false,
23    "is_vpn": true,
24    "proxy_confidence_score": 0,
25    "proxy_last_seen": "",
26    "proxy_provider_names": [],
27    "relay_provider_name": "",
28    "threat_score": 80,
29    "vpn_confidence_score": 70,
30    "vpn_last_seen": "",
31    "vpn_provider_names": []
32  }
33}

For full API specifications, refer to the official IP Security API documentation.

IV. Request with Field Filtering ip-security

ipgeolocation ip-security --ip 195.154.221.54 --fields security.is_tor,security.is_proxy,security.is_bot,security.is_spam

Sample output:

Response Preview

1{
2  "ip": "195.154.221.54",
3  "security": {
4    "is_bot": false,
5    "is_proxy": false,
6    "is_spam": false,
7    "is_tor": false
8  }
9}

6. bulk-ip-security Command

Look up IP security information for multiple IP addresses in one request.

I. bulk-ip-security Usage

ipgeolocation bulk-ip-security [flags]

II. Flags for bulk-ip-security

Flag	Type	Default	Description
`--ips`	string[]	`[]`	Comma-separated list of IPs. Example: `--ips 8.8.8.8,1.1.1.1`
`--file`	string	`""`	Path to a text file containing IPs (one per line).
`--exclude`	string[]	`[]`	Exclude fields (e.g. `security.is_tor`).
`--fields`	string[]	`[]`	Return only specific fields (e.g. `security.threat_score`).
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.
`--output-file`	string	`""`	Save output to JSON file. Example: `--output-file results`

III. bulk-ip-security Examples

Look up 3 IP addresses:

ipgeolocation bulk-ip-security --ips 8.8.8.8,1.1.1.1,192.30.253.112

Look up from a file:

ipgeolocation bulk-ip-security --file=ips.txt --output-file=output

Output as YAML:

ipgeolocation bulk-ip-security --ips=8.8.8.8 --output=yaml

Save results to a JSON file:

ipgeolocation bulk-ip-security --ips=8.8.8.8,1.1.1.1 --output-file=output

For further information, please visit Bulk IP Security API Documentation.

7. asn Command

Look up ASN (Autonomous System Number) information using the ipgeolocation.io API.

I. asn Usage

ipgeolocation asn [flags]

II. Flags for asn

Flag	Type	Default	Description
`--ip`	string	`""`	IPv4 or IPv6 address.
`--include`	string[]	`[]`	Include extra fields in output.(e.g., `peers, downstreams, upstreams, routes, whois_response`)
`--exclude`	string[]	`[]`	Exclude fields from output.
`--fields`	string[]	`[]`	Return only specific fields (e.g. `ip,organization`).
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

III. Get ASN Information of your IP

Get ASN information about your current IP address:

ipgeolocation asn

IV. Get ASN Information by ASN Number

Look up a specific ASN. The AS number can be prefixed with 'AS' or 'as':

ipgeolocation asn --asn 15169

Sample output:

Response Preview

1{
2  "asn": {
3    "as_number": "AS15169",
4    "organization": "Google LLC",
5    "country": "US",
6    "asn_name": "GOOGLE",
7    "type": "BUSINESS",
8    "domain": "google.com",
9    "date_allocated": "",
10    "allocation_status": "",
11    "num_of_ipv4_routes": "1026",
12    "num_of_ipv6_routes": "106",
13    "rir": "ARIN"
14  }
15}

V. Combine all objects using Include

Look up a specific IP, including additional fields:

ipgeolocation asn --asn 12 --include routes,peers,upstreams,downstreams,whois_response

Sample output:

Response Preview

1{
2  "asn": {
3    "as_number": "AS12",
4    "organization": "New York University",
5    "country": "US",
6    "asn_name": "NYU-DOMAIN",
7    "type": "EDUCATION",
8    "domain": "nyu.edu",
9    "date_allocated": "",
10    "allocation_status": "",
11    "num_of_ipv4_routes": "11",
12    "num_of_ipv6_routes": "1",
13    "rir": "ARIN",
14    "routes": [
15      "192.76.177.0/24",
16      "...",
17      "216.165.103.0/24"
18    ],
19    "upstreams": [
20      {
21        "as_number": "AS3269",
22        "description": "Telecom Italia S.p.A.",
23        "country": "IT"
24      },
25      "...",
26      {
27        "as_number": "AS137",
28        "description": "Consortium GARR",
29        "country": "IT"
30      }
31    ],
32    "downstreams": [
33      {
34        "as_number": "AS394666",
35        "description": "NYU Langone Health",
36        "country": "US"
37      },
38      {
39        "as_number": "AS54965",
40        "description": "Polytechnic Institute of NYU",
41        "country": "US"
42      }
43    ],
44    "peers": [
45      {
46        "as_number": "AS3269",
47        "description": "Telecom Italia S.p.A.",
48        "country": "IT"
49      },
50      "...",
51      {
52        "as_number": "AS54965",
53        "description": "Polytechnic Institute of NYU",
54        "country": "US"
55      }
56    ],
57    "whois_response": "<raw-whois-response>"
58  }
59}

Exclude unnecessary fields:

ipgeolocation asn --ip 8.8.8.8 --exclude asn.date_allocated,asn.allocation_status

Sample output:

Response Preview

1{
2  "asn": {
3    "as_number": "AS15169",
4    "asn_name": "GOOGLE",
5    "country": "US",
6    "domain": "google.com",
7    "num_of_ipv4_routes": "1024",
8    "num_of_ipv6_routes": "135",
9    "organization": "Google LLC",
10    "rir": "ARIN",
11    "type": "BUSINESS"
12  },
13  "ip": "8.8.8.8"
14}

Get only specific fields in table format:

ipgeolocation asn --ip 8.8.8.8 --fields asn.organization,asn.country,asn.downstreams --output table

Output as YAML:

ipgeolocation asn --ip 8.8.8.8 --output=yaml

For further information, please visit ASN API Documentation.

8. abuse Command

Look up IP abuse contact information using the ipgeolocation.io API.

I. abuse Usage

ipgeolocation abuse [flags]

II. Flags for abuse

Flag	Type	Default	Description
`--ip`	string	`""`	IPv4 or IPv6 address.
`--exclude`	string[]	`[]`	Exclude fields from output.
`--fields`	string[]	`[]`	Return only specific fields (e.g. `ip,organization`).
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

III. Get abuse info about your current IP

ipgeolocation abuse

IV. Look up a specific IP

ipgeolocation abuse --ip 8.8.8.8

V. Exclude unnecessary fields

ipgeolocation abuse --ip 8.8.8.8 --exclude abuse.emails

VI. Lookup Abuse Contact with Specific Fields

ipgeolocation abuse --ip 8.8.8.8 --fields abuse.emails --output table

Sample output:

Response Preview

1Ip                  : 8.8.8.8
2Abuse:
3  Emails:
4    [0]:
5      network-abuse@google.com

Get output as YAML:

ipgeolocation abuse --ip 8.8.8.8 --output=yaml

Sample output:

Response Preview

1abuse:
2    address: |-
3        1600 Amphitheatre Parkway
4        Mountain View
5        CA
6        94043
7        United States
8    country: ""
9    emails:
10        - network-abuse@google.com
11    kind: group
12    name: Abuse
13    organization: Abuse
14    phone_numbers:
15        - +1-650-253-0000
16    route: 8.8.8.0/24
17ip: 8.8.8.8

For further information, please visit Abuse API Documentation.

9. timezone Command

Look up timezone information using the ipgeolocation.io API with different query types like IP address, latitude/longitude, and timezone ID.

For full API specifications, refer to the Time Zone API documentation.

I. timezone Usage

ipgeolocation timezone [flags]

II. Flags for timezone

Flag	Type	Default	Description
`--ip`	string	`""`	IPv4 or IPv6 address.
`--tz`	string	`""`	IANA Timezone identifier.
`--location`	string	`""`	Location name (e.g. New York)
`--latitude`	float64	`0`	Latitude (e.g. 37.7749).
`--longitude`	float64	`0`	Longitude (e.g., -122.4194).
`--lang`	string	`""`	Response language (if supported).
`--iata`	string	`""`	IATA code (e.g. DXB).
`--icao`	string	`""`	ICAO code (e.g. KATL).
`--lo`	string	`""`	LO code (e.g. DEBER).
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

III. Get timezone info about your current IP

ipgeolocation timezone

IV. Get Timezone for a specific IP Address

ipgeolocation timezone --ip 8.8.8.8

Sample output:

Response Preview

1{
2  "ip": "8.8.8.8",
3  "location": {
4    "city": "Mountain View",
5    "continent_code": "NA",
6    "continent_name": "North America",
7    "country_code2": "US",
8    "country_code3": "USA",
9    "country_name": "United States",
10    "country_name_official": "United States of America",
11    "district": "Santa Clara",
12    "is_eu": false,
13    "latitude": "37.42240",
14    "longitude": "-122.08421",
15    "state_code": "US-CA",
16    "state_prov": "California",
17    "zipcode": "94043-1351"
18  },
19  "time_zone": {
20    "current_time": "2026-03-03 03:22:55.618-0800",
21    "current_time_unix": 1772536975.618,
22    "current_tz_abbreviation": "PST",
23    "current_tz_full_name": "Pacific Standard Time",
24    "date": "2026-03-03",
25    "date_time": "2026-03-03 03:22:55",
26    "date_time_txt": "Tuesday, March 03, 2026 03:22:55",
27    "date_time_wti": "Tue, 03 Mar 2026 03:22:55 -0800",
28    "date_time_ymd": "2026-03-03T03:22:55-0800",
29    "dst_end": {
30      "date_time_after": "2026-11-01 TIME 01:00",
31      "date_time_before": "2026-11-01 TIME 02:00",
32      "duration": "-1.00H",
33      "gap": false,
34      "overlap": true,
35      "utc_time": "2026-11-01 TIME 09:00"
36    },
37    "dst_exists": true,
38    "dst_savings": 0,
39    "dst_start": {
40      "date_time_after": "2026-03-08 TIME 03:00",
41      "date_time_before": "2026-03-08 TIME 02:00",
42      "duration": "+1.00H",
43      "gap": true,
44      "overlap": false,
45      "utc_time": "2026-03-08 TIME 10:00"
46    },
47    "dst_tz_abbreviation": "PDT",
48    "dst_tz_full_name": "Pacific Daylight Time",
49    "is_dst": false,
50    "month": 3,
51    "name": "America/Los_Angeles",
52    "offset": -8,
53    "offset_with_dst": -8,
54    "standard_tz_abbreviation": "PST",
55    "standard_tz_full_name": "Pacific Standard Time",
56    "time_12": "03:22:55 AM",
57    "time_24": "03:22:55",
58    "week": 10,
59    "year": 2026,
60    "year_abbr": "26"
61  }
62}

V. Get Timezone by Timezone Name

ipgeolocation timezone --tz America/New_York

Sample output:

Response Preview

1{
2  "time_zone": {
3    "current_time": "2026-03-03 06:23:30.451-0500",
4    "current_time_unix": 1772537010.451,
5    "current_tz_abbreviation": "EST",
6    "current_tz_full_name": "Eastern Standard Time",
7    "date": "2026-03-03",
8    "date_time": "2026-03-03 06:23:30",
9    "date_time_txt": "Tuesday, March 03, 2026 06:23:30",
10    "date_time_wti": "Tue, 03 Mar 2026 06:23:30 -0500",
11    "date_time_ymd": "2026-03-03T06:23:30-0500",
12    "dst_end": {
13      "date_time_after": "2026-11-01 TIME 01:00",
14      "date_time_before": "2026-11-01 TIME 02:00",
15      "duration": "-1.00H",
16      "gap": false,
17      "overlap": true,
18      "utc_time": "2026-11-01 TIME 06:00"
19    },
20    "dst_exists": true,
21    "dst_savings": 0,
22    "dst_start": {
23      "date_time_after": "2026-03-08 TIME 03:00",
24      "date_time_before": "2026-03-08 TIME 02:00",
25      "duration": "+1.00H",
26      "gap": true,
27      "overlap": false,
28      "utc_time": "2026-03-08 TIME 07:00"
29    },
30    "dst_tz_abbreviation": "EDT",
31    "dst_tz_full_name": "Eastern Daylight Time",
32    "is_dst": false,
33    "month": 3,
34    "name": "America/New_York",
35    "offset": -5,
36    "offset_with_dst": -5,
37    "standard_tz_abbreviation": "EST",
38    "standard_tz_full_name": "Eastern Standard Time",
39    "time_12": "06:23:30 AM",
40    "time_24": "06:23:30",
41    "week": 10,
42    "year": 2026,
43    "year_abbr": "26"
44  }
45}

VI. Get Timezone from Any Address

ipgeolocation timezone --location "New York, USA"

Sample output:

Response Preview

1{
2  "location": {
3    "city": "Syracuse",
4    "country_name": "United States",
5    "latitude": "43.06923",
6    "locality": "Destiny USA Mall",
7    "location_string": "New York, USA",
8    "longitude": "-76.17249",
9    "state_prov": "New York"
10  },
11  "time_zone": {
12    "current_time": "2026-03-03 06:24:17.824-0500",
13    "current_time_unix": 1772537057.824,
14    "current_tz_abbreviation": "EST",
15    "current_tz_full_name": "Eastern Standard Time",
16    "date": "2026-03-03",
17    "date_time": "2026-03-03 06:24:17",
18    "date_time_txt": "Tuesday, March 03, 2026 06:24:17",
19    "date_time_wti": "Tue, 03 Mar 2026 06:24:17 -0500",
20    "date_time_ymd": "2026-03-03T06:24:17-0500",
21    "dst_end": {
22      "date_time_after": "2026-11-01 TIME 01:00",
23      "date_time_before": "2026-11-01 TIME 02:00",
24      "duration": "-1.00H",
25      "gap": false,
26      "overlap": true,
27      "utc_time": "2026-11-01 TIME 06:00"
28    },
29    "dst_exists": true,
30    "dst_savings": 0,
31    "dst_start": {
32      "date_time_after": "2026-03-08 TIME 03:00",
33      "date_time_before": "2026-03-08 TIME 02:00",
34      "duration": "+1.00H",
35      "gap": true,
36      "overlap": false,
37      "utc_time": "2026-03-08 TIME 07:00"
38    },
39    "dst_tz_abbreviation": "EDT",
40    "dst_tz_full_name": "Eastern Daylight Time",
41    "is_dst": false,
42    "month": 3,
43    "name": "America/New_York",
44    "offset": -5,
45    "offset_with_dst": -5,
46    "standard_tz_abbreviation": "EST",
47    "standard_tz_full_name": "Eastern Standard Time",
48    "time_12": "06:24:17 AM",
49    "time_24": "06:24:17",
50    "week": 10,
51    "year": 2026,
52    "year_abbr": "26"
53  }
54}

VII. Get Timezone from Location Coordinates

ipgeolocation timezone --latitude 37.7749 --longitude -122.4194

Sample output:

Response Preview

1{
2  "time_zone": {
3    "current_time": "2026-03-03 03:25:00.249-0800",
4    "current_time_unix": 1772537100.249,
5    "current_tz_abbreviation": "PST",
6    "current_tz_full_name": "Pacific Standard Time",
7    "date": "2026-03-03",
8    "date_time": "2026-03-03 03:25:00",
9    "date_time_txt": "Tuesday, March 03, 2026 03:25:00",
10    "date_time_wti": "Tue, 03 Mar 2026 03:25:00 -0800",
11    "date_time_ymd": "2026-03-03T03:25:00-0800",
12    "dst_end": {
13      "date_time_after": "2026-11-01 TIME 01:00",
14      "date_time_before": "2026-11-01 TIME 02:00",
15      "duration": "-1.00H",
16      "gap": false,
17      "overlap": true,
18      "utc_time": "2026-11-01 TIME 09:00"
19    },
20    "dst_exists": true,
21    "dst_savings": 0,
22    "dst_start": {
23      "date_time_after": "2026-03-08 TIME 03:00",
24      "date_time_before": "2026-03-08 TIME 02:00",
25      "duration": "+1.00H",
26      "gap": true,
27      "overlap": false,
28      "utc_time": "2026-03-08 TIME 10:00"
29    },
30    "dst_tz_abbreviation": "PDT",
31    "dst_tz_full_name": "Pacific Daylight Time",
32    "is_dst": false,
33    "month": 3,
34    "name": "America/Los_Angeles",
35    "offset": -8,
36    "offset_with_dst": -8,
37    "standard_tz_abbreviation": "PST",
38    "standard_tz_full_name": "Pacific Standard Time",
39    "time_12": "03:25:00 AM",
40    "time_24": "03:25:00",
41    "week": 10,
42    "year": 2026,
43    "year_abbr": "26"
44  }
45}

VIII. Get Timezone and Airport Details from IATA Code

ipgeolocation timezone --iata DXB

Sample output:

Response Preview

1{
2  "airport_details": {
3    "city": "Dubai",
4    "continent_code": "AS",
5    "country_code": "AE",
6    "elevation_ft": 62,
7    "faa_code": "",
8    "iata_code": "DXB",
9    "icao_code": "OMDB",
10    "latitude": "25.25280",
11    "longitude": "55.36440",
12    "name": "Dubai International Airport",
13    "state_code": "AE-DU",
14    "type": "large_airport"
15  },
16  "time_zone": {
17    "current_time": "2026-03-03 15:26:04.634+0400",
18    "current_time_unix": 1772537164.634,
19    "current_tz_abbreviation": "GST",
20    "current_tz_full_name": "Gulf Standard Time",
21    "date": "2026-03-03",
22    "date_time": "2026-03-03 15:26:04",
23    "date_time_txt": "Tuesday, March 03, 2026 15:26:04",
24    "date_time_wti": "Tue, 03 Mar 2026 15:26:04 +0400",
25    "date_time_ymd": "2026-03-03T15:26:04+0400",
26    "dst_end": {},
27    "dst_exists": false,
28    "dst_savings": 0,
29    "dst_start": {},
30    "dst_tz_abbreviation": "",
31    "dst_tz_full_name": "",
32    "is_dst": false,
33    "month": 3,
34    "name": "Asia/Dubai",
35    "offset": 4,
36    "offset_with_dst": 4,
37    "standard_tz_abbreviation": "GST",
38    "standard_tz_full_name": "Gulf Standard Time",
39    "time_12": "03:26:04 PM",
40    "time_24": "15:26:04",
41    "week": 10,
42    "year": 2026,
43    "year_abbr": "26"
44  }
45}

IX. Get Timezone and City Details from UN/LOCODE

ipgeolocation timezone --lo DEBER

Sample output:

Response Preview

1{
2  "lo_code_details": {
3    "city": "Berlin",
4    "country_code": "DE",
5    "country_name": "",
6    "latitude": "52.51667",
7    "lo_code": "DEBER",
8    "location_type": "Port, Rail Terminal, Road Terminal, Airport, Postal Exchange",
9    "longitude": "13.38333",
10    "state_code": "BE"
11  },
12  "time_zone": {
13    "current_time": "2026-03-03 12:26:32.849+0100",
14    "current_time_unix": 1772537192.849,
15    "current_tz_abbreviation": "CET",
16    "current_tz_full_name": "Central European Standard Time",
17    "date": "2026-03-03",
18    "date_time": "2026-03-03 12:26:32",
19    "date_time_txt": "Tuesday, March 03, 2026 12:26:32",
20    "date_time_wti": "Tue, 03 Mar 2026 12:26:32 +0100",
21    "date_time_ymd": "2026-03-03T12:26:32+0100",
22    "dst_end": {
23      "date_time_after": "2026-10-25 TIME 02:00",
24      "date_time_before": "2026-10-25 TIME 03:00",
25      "duration": "-1.00H",
26      "gap": false,
27      "overlap": true,
28      "utc_time": "2026-10-25 TIME 01:00"
29    },
30    "dst_exists": true,
31    "dst_savings": 0,
32    "dst_start": {
33      "date_time_after": "2026-03-29 TIME 03:00",
34      "date_time_before": "2026-03-29 TIME 02:00",
35      "duration": "+1.00H",
36      "gap": true,
37      "overlap": false,
38      "utc_time": "2026-03-29 TIME 01:00"
39    },
40    "dst_tz_abbreviation": "CEST",
41    "dst_tz_full_name": "Central European Summer Time",
42    "is_dst": false,
43    "month": 3,
44    "name": "Europe/Berlin",
45    "offset": 1,
46    "offset_with_dst": 1,
47    "standard_tz_abbreviation": "CET",
48    "standard_tz_full_name": "Central European Standard Time",
49    "time_12": "12:26:32 PM",
50    "time_24": "12:26:32",
51    "week": 10,
52    "year": 2026,
53    "year_abbr": "26"
54  }
55}

Output as YAML:

ipgeolocation timezone --ip 8.8.8.8 --output=yaml

10. time-conversion Command

Convert between timezones using the ipgeolocation.io API to convert a specific time from one timezone to another using timezone identifiers and optional date/time inputs.

For more details, refer to the official documentation: Timezone Converter API.

I. time-conversion Usage

ipgeolocation time-conversion [flags]

II. Flags for time-conversion

Flag	Type	Default	Description
`--tz_from`	string	`""`	Timezone to convert from.
`--tz_to`	string	`""`	Timezone to convert to.
`--location_from`	string	`""`	Location to convert from.
`--location_to`	string	`""`	Location to convert to.
`--lat_from`	float64	`0`	Latitude to convert from.
`--long_from`	float64	`0`	Longitude to convert from.
`--lat_to`	float64	`0`	Latitude to convert to.
`--long_to`	float64	`0`	Longitude to convert to.
`--iata_from`	string	`""`	IATA code to convert from.
`--iata_to`	string	`""`	IATA code to convert to.
`--icao_from`	string	`""`	ICAO code to convert from.
`--icao_to`	string	`""`	ICAO code to convert to.
`--lo_from`	string	`""`	LO code to convert from.
`--lo_to`	string	`""`	LO code to convert to.
`--time`	string	`""`	Time to convert.
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

III. Convert Current Time from One Timezone to Another

ipgeolocation time-conversion --tz_from America/New_York --tz_to Europe/London

Sample output:

Response Preview

1{
2  "original_time": "2026-01-13 07:22:43",
3  "converted_time": "2026-01-13 12:22:43",
4  "diff_hour": 5,
5  "diff_min": 300
6}

Convert from one location to another:

ipgeolocation time-conversion --location_from "New York" --location_to London

Convert from one latitude and longitude to another:

ipgeolocation time-conversion --lat_from 37.7749 --long_from -122.4194 --lat_to 51.509865 --long_to -0.118092

Convert from one IATA code to another:

ipgeolocation time-conversion --iata_from DXB --iata_to JFK

Convert from one ICAO code to another (Atlanta to Newark):

ipgeolocation time-conversion --icao_from KATL --icao_to KEWR

Convert from one UN/LOCODE to another (Berlin to New York):

ipgeolocation time-conversion --lo_from DEBER --lo_to USNYC

Output as YAML:

ipgeolocation time-conversion --tz_from America/New_York --tz_to Europe/London --output=yaml

11. astronomy Command

The astronomy command uses the IPGeolocation.io Astronomy API to fetch astronomy-related data such as:

Sunrise and sunset
Solar noon
Moonrise and moonset
Moon phase
Day length

Choose the calculation location with an IP address, location name, or latitude/longitude. Use --tz to display the event times in another IANA time zone; it does not select a location.

For further information, please visit Astronomy API Documentation.

I. astronomy Usage

ipgeolocation astronomy [flags]

II. Flags for astronomy

Flag	Type	Default	Description
`--ip`	string	`""`	IPv4 or IPv6 address.
`--location`	string	`""`	City name.
`--latitude`	float64	`0`	Latitude.
`--longitude`	float64	`0`	Longitude.
`--lang`	string	`""`	Response language (if supported).
`--tz`	string	`""`	IANA time zone for output timestamps.
`--elevation`	float64	`0`	Elevation.
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

III. Lookup Astronomy API by Coordinates

Get astronomy info about a specific latitude and longitude:

ipgeolocation astronomy --latitude 37.7749 --longitude -122.4194

Sample output:

Response Preview

1{
2  "astronomy": {
3    "current_time": "05:07:18.340",
4    "date": "2026-01-13",
5    "day_length": "09:50",
6    "evening": {
7      "astronomical_twilight_begin": "18:14",
8      "astronomical_twilight_end": "18:45",
9      "blue_hour_begin": "17:30",
10      "blue_hour_end": "17:52",
11      "civil_twilight_begin": "17:13",
12      "civil_twilight_end": "17:41",
13      "golden_hour_begin": "16:33",
14      "golden_hour_end": "17:30",
15      "nautical_twilight_begin": "17:41",
16      "nautical_twilight_end": "18:14"
17    },
18    "mid_night": "00:18",
19    "moon_altitude": 16.07194223979877,
20    "moon_angle": 301.4632703453228,
21    "moon_azimuth": 138.83883667429063,
22    "moon_distance": 405270.18931629026,
23    "moon_illumination_percentage": "-23.90",
24    "moon_parallactic_angle": -34.64165014870525,
25    "moon_phase": "WANING_CRESCENT",
26    "moon_status": "-",
27    "moonrise": "03:17",
28    "moonset": "12:53",
29    "morning": {
30      "astronomical_twilight_begin": "05:51",
31      "astronomical_twilight_end": "06:23",
32      "blue_hour_begin": "06:44",
33      "blue_hour_end": "07:06",
34      "civil_twilight_begin": "06:55",
35      "civil_twilight_end": "07:23",
36      "golden_hour_begin": "07:06",
37      "golden_hour_end": "08:04",
38      "nautical_twilight_begin": "06:23",
39      "nautical_twilight_end": "06:55"
40    },
41    "night_begin": "18:45",
42    "night_end": "05:51",
43    "solar_noon": "12:18",
44    "sun_altitude": -26.63562944381545,
45    "sun_azimuth": 97.35878744233418,
46    "sun_distance": 147120665.60394213,
47    "sun_status": "-",
48    "sunrise": "07:23",
49    "sunset": "17:13"
50  },
51  "location": {
52    "city": "San Francisco",
53    "country_name": "United States",
54    "elevation": "16",
55    "latitude": "37.77490",
56    "locality": "South of Market",
57    "longitude": "-122.41940",
58    "state_prov": "California"
59  }
60}

IV. Lookup Astronomy API by IP Address

Get astronomy info about your current IP:

ipgeolocation astronomy

Get astronomy information for a specific IP address:

ipgeolocation astronomy --ip 8.8.8.8

Sample output:

Response Preview

1{
2  "astronomy": {
3    "current_time": "05:09:04.314",
4    "date": "2026-01-13",
5    "day_length": "09:50",
6    "evening": {
7      "astronomical_twilight_begin": "18:13",
8      "astronomical_twilight_end": "18:44",
9      "blue_hour_begin": "17:30",
10      "blue_hour_end": "17:51",
11      "civil_twilight_begin": "17:12",
12      "civil_twilight_end": "17:41",
13      "golden_hour_begin": "16:33",
14      "golden_hour_end": "17:30",
15      "nautical_twilight_begin": "17:41",
16      "nautical_twilight_end": "18:13"
17    },
18    "mid_night": "00:16",
19    "moon_altitude": 16.728478792843955,
20    "moon_angle": 301.47655895571256,
21    "moon_azimuth": 139.37283119065324,
22    "moon_distance": 405270.54014008155,
23    "moon_illumination_percentage": "-23.89",
24    "moon_parallactic_angle": -34.405427656780056,
25    "moon_phase": "WANING_CRESCENT",
26    "moon_status": "-",
27    "moonrise": "03:15",
28    "moonset": "12:53",
29    "morning": {
30      "astronomical_twilight_begin": "05:50",
31      "astronomical_twilight_end": "06:21",
32      "blue_hour_begin": "06:42",
33      "blue_hour_end": "07:04",
34      "civil_twilight_begin": "06:53",
35      "civil_twilight_end": "07:21",
36      "golden_hour_begin": "07:04",
37      "golden_hour_end": "08:01",
38      "nautical_twilight_begin": "06:21",
39      "nautical_twilight_end": "06:53"
40    },
41    "night_begin": "18:44",
42    "night_end": "05:50",
43    "solar_noon": "12:17",
44    "sun_altitude": -25.978681889301882,
45    "sun_azimuth": 97.96459578152059,
46    "sun_distance": 147120665.60394216,
47    "sun_status": "-",
48    "sunrise": "07:21",
49    "sunset": "17:12"
50  },
51  "ip": "8.8.8.8",
52  "location": {
53    "city": "Mountain View",
54    "continent_code": "NA",
55    "continent_name": "North America",
56    "country_code2": "US",
57    "country_code3": "USA",
58    "country_name": "United States",
59    "country_name_official": "United States of America",
60    "district": "Santa Clara",
61    "elevation": "3",
62    "is_eu": false,
63    "latitude": "37.42240",
64    "locality": "Charleston Terrace",
65    "longitude": "-122.08421",
66    "state_code": "US-CA",
67    "state_prov": "California",
68    "zipcode": "94043-1351"
69  }
70}

V. Lookup Astronomy API by Location String

ipgeolocation astronomy --location "New York, USA"

Sample output:

Response Preview

1{
2  "astronomy": {
3    "current_time": "08:10:53.180",
4    "date": "2026-01-13",
5    "day_length": "09:23",
6    "evening": {
7      "astronomical_twilight_begin": "17:59",
8      "astronomical_twilight_end": "18:34",
9      "blue_hour_begin": "17:12",
10      "blue_hour_end": "17:36",
11      "civil_twilight_begin": "16:55",
12      "civil_twilight_end": "17:24",
13      "golden_hour_begin": "16:08",
14      "golden_hour_end": "17:12",
15      "nautical_twilight_begin": "17:24",
16      "nautical_twilight_end": "17:59"
17    },
18    "mid_night": "00:13",
19    "moon_altitude": 23.12401867639373,
20    "moon_angle": 301.4902102354391,
21    "moon_azimuth": 183.36677049153406,
22    "moon_distance": 405270.8986986421,
23    "moon_illumination_percentage": "-23.88",
24    "moon_parallactic_angle": 2.6870094296532643,
25    "moon_phase": "WANING_CRESCENT",
26    "moon_status": "-",
27    "moonrise": "03:20",
28    "moonset": "12:27",
29    "morning": {
30      "astronomical_twilight_begin": "05:53",
31      "astronomical_twilight_end": "06:27",
32      "blue_hour_begin": "06:50",
33      "blue_hour_end": "07:14",
34      "civil_twilight_begin": "07:02",
35      "civil_twilight_end": "07:32",
36      "golden_hour_begin": "07:14",
37      "golden_hour_end": "08:18",
38      "nautical_twilight_begin": "06:27",
39      "nautical_twilight_end": "07:02"
40    },
41    "night_begin": "18:34",
42    "night_end": "05:53",
43    "solar_noon": "12:13",
44    "sun_altitude": 4.828766240317727,
45    "sun_azimuth": 125.48815354581939,
46    "sun_distance": 147120665.60394213,
47    "sun_status": "-",
48    "sunrise": "07:32",
49    "sunset": "16:55"
50  },
51  "location": {
52    "city": "Syracuse",
53    "country_name": "United States",
54    "elevation": "128",
55    "latitude": "43.06923",
56    "locality": "Destiny USA Mall",
57    "location_string": "New York, USA",
58    "longitude": "-76.17249",
59    "state_prov": "New York"
60  }
61}

12. astronomy-timeseries Command

The astronomy-timeseries command uses the IPGeolocation.io Astronomy API to fetch astronomy-related data such as:

Sunrise and sunset
Solar noon
Moonrise and moonset
Moon phase
Day length

Choose the calculation location with an IP address, location name, or latitude/longitude.

For further information, please visit Astronomy Timeseries API Documentation.

I. astronomy-timeseries Usage

ipgeolocation astronomy-timeseries [flags]

II. Flags for astronomy-timeseries

Flag	Type	Default	Description
`--ip`	string	`""`	IPv4 or IPv6 address.
`--location`	string	`""`	City name.
`--latitude`	float64	`0`	Latitude.
`--longitude`	float64	`0`	Longitude.
`--lang`	string	`""`	Response language (if supported).
`--start-date`	string	`""`	Start date (e.g. 2023-01-01) Only YYYY-MM-DD.
`--end-date`	string	`""`	End date (e.g. 2023-12-31) Only YYYY-MM-DD
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

III. Get astronomy timeseries info for an IP address

For your own IP address

ipgeolocation astronomy-timeseries --start-date 2023-01-01 --end-date 2023-01-02

IV. Get astronomy timeseries about a specific lat and lon

ipgeolocation astronomy-timeseries --latitude 37.7749 --longitude -122.4194 --start-date 2023-01-01 --end-date 2023-01-02

V. Get astronomy timeseries about a specific location

ipgeolocation astronomy-timeseries --location "New York, USA" --start-date 2023-01-01 --end-date 2023-01-02

Sample output:

Response Preview

1{
2  "astronomy": [
3    {
4      "date": "2023-01-01",
5      "day_length": "09:08",
6      "evening": {
7        "astronomical_twilight_begin": "17:48",
8        "astronomical_twilight_end": "18:23",
9        "blue_hour_begin": "17:00",
10        "blue_hour_end": "17:24",
11        "civil_twilight_begin": "16:42",
12        "civil_twilight_end": "17:12",
13        "golden_hour_begin": "15:54",
14        "golden_hour_end": "17:00",
15        "nautical_twilight_begin": "17:12",
16        "nautical_twilight_end": "17:48"
17      },
18      "mid_night": "00:08",
19      "moon_phase": "WAXING_GIBBOUS",
20      "moon_status": "-",
21      "moonrise": "12:59",
22      "moonset": "02:38",
23      "morning": {
24        "astronomical_twilight_begin": "05:53",
25        "astronomical_twilight_end": "06:28",
26        "blue_hour_begin": "06:51",
27        "blue_hour_end": "07:16",
28        "civil_twilight_begin": "07:04",
29        "civil_twilight_end": "07:34",
30        "golden_hour_begin": "07:16",
31        "golden_hour_end": "08:22",
32        "nautical_twilight_begin": "06:28",
33        "nautical_twilight_end": "07:04"
34      },
35      "night_begin": "18:23",
36      "night_end": "05:53",
37      "solar_noon": "12:08",
38      "sun_status": "-",
39      "sunrise": "07:34",
40      "sunset": "16:42"
41    },
42    {
43      "date": "2023-01-02",
44      "day_length": "09:09",
45      "evening": {
46        "astronomical_twilight_begin": "17:49",
47        "astronomical_twilight_end": "18:23",
48        "blue_hour_begin": "17:01",
49        "blue_hour_end": "17:25",
50        "civil_twilight_begin": "16:43",
51        "civil_twilight_end": "17:13",
52        "golden_hour_begin": "15:55",
53        "golden_hour_end": "17:01",
54        "nautical_twilight_begin": "17:13",
55        "nautical_twilight_end": "17:49"
56      },
57      "mid_night": "00:08",
58      "moon_phase": "WAXING_GIBBOUS",
59      "moon_status": "-",
60      "moonrise": "13:25",
61      "moonset": "03:45",
62      "morning": {
63        "astronomical_twilight_begin": "05:53",
64        "astronomical_twilight_end": "06:28",
65        "blue_hour_begin": "06:52",
66        "blue_hour_end": "07:16",
67        "civil_twilight_begin": "07:04",
68        "civil_twilight_end": "07:34",
69        "golden_hour_begin": "07:16",
70        "golden_hour_end": "08:22",
71        "nautical_twilight_begin": "06:28",
72        "nautical_twilight_end": "07:04"
73      },
74      "night_begin": "18:23",
75      "night_end": "05:53",
76      "solar_noon": "12:08",
77      "sun_status": "-",
78      "sunrise": "07:34",
79      "sunset": "16:43"
80    }
81  ],
82  "location": {
83    "city": "Syracuse",
84    "country_name": "United States",
85    "elevation": "128",
86    "latitude": "43.06923",
87    "locality": "Destiny USA Mall",
88    "location_string": "New York, USA",
89    "longitude": "-76.17249",
90    "state_prov": "New York"
91  }
92}

13. parse-user-agent Command

The parse-user-agent command uses the IPGeolocation.io User Agent API to parse user agent strings and extract relevant information such as:

Device type
Operating system
Browser
Browser version
Device vendor
Device model

I. parse-user-agent Usage

ipgeolocation parse-user-agent [flags]

II. Flags for parse-user-agent

Flag	Type	Default	Description
`--user-agent`	string	`""`	User agent string.
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

For further information, please visit User Agent API Documentation.

III. Parse a user agent string

ipgeolocation parse-user-agent --user-agent "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36"

Sample output:

Response Preview

1{
2  "device": {
3    "brand": "Unknown",
4    "cpu": "Intel x86_64",
5    "name": "Desktop",
6    "type": "Desktop"
7  },
8  "engine": {
9    "name": "Blink",
10    "type": "Browser",
11    "version": "58.0",
12    "version_major": "58"
13  },
14  "name": "Chrome",
15  "operating_system": {
16    "build": "??",
17    "name": "Windows NT",
18    "type": "Desktop",
19    "version": "10.0",
20    "version_major": "10"
21  },
22  "type": "Browser",
23  "user_agent_string": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36",
24  "version": "58.0.3029.110",
25  "version_major": "58"
26}

14. parse-bulk-user-agents Command

The parse-bulk-user-agents command uses the bulk endpoint of the IPGeolocation.io User Agent API to parse multiple user agent strings and extract relevant information such as:

Device type
Operating system
Browser
Browser version
Device vendor
Device model

I. parse-bulk-user-agents Usage

ipgeolocation parse-bulk-user-agents [flags]

II. Flags for parse-bulk-user-agents

Flag	Type	Default	Description
`--user-agents`	string[]	`[]`	User agent strings.
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

For further information, please visit User Agent API bulk parsing documentation.

III. Parse multiple user agent strings

ipgeolocation parse-bulk-user-agents --user-agents "Mozilla/5.0 (Windows NT 10.0; Win64; x64)","curl/7.64.1"

Sample output:

Response Preview

1[
2  {
3    "device": {
4      "brand": "Unknown",
5      "cpu": "Intel x86_64",
6      "name": "Desktop",
7      "type": "Desktop"
8    },
9    "engine": {
10      "name": "Mozilla",
11      "type": "Browser",
12      "version": "5.0",
13      "version_major": "5"
14    },
15    "name": "Windows NT",
16    "operating_system": {
17      "build": "??",
18      "name": "Windows NT",
19      "type": "Desktop",
20      "version": "10.0",
21      "version_major": "10"
22    },
23    "type": "Browser",
24    "user_agent_string": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
25    "version": "10.0",
26    "version_major": "10"
27  },
28  {
29    "device": {
30      "brand": "Curl",
31      "cpu": "Unknown",
32      "name": "Curl",
33      "type": "Robot"
34    },
35    "engine": {
36      "name": "curl",
37      "type": "Robot",
38      "version": "7.64.1",
39      "version_major": "7"
40    },
41    "name": "Curl",
42    "operating_system": {
43      "build": "??",
44      "name": "Cloud",
45      "type": "Cloud",
46      "version": "??",
47      "version_major": "??"
48    },
49    "type": "Robot",
50    "user_agent_string": "curl/7.64.1",
51    "version": "7.64.1",
52    "version_major": "7"
53  }
54]

License

This project is released under the MIT License.