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 enables developers, DevOps engineers, network operators, and security teams to retrieve IP intelligence without writing any 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 Location API: Get all-in-one unified solution for location (city, locality, state, country, etc.), currency, network (AS number, ASN name, organization, asn type, date of allocation, company/ISP name, company type, company domain), timezone , useragent string parsing, security (threat score, is_tor, is_bot, proxy_provider, cloud_provider), and abuse contact (route/CIDR network, country, address, email, phone numbers) information.
IP Security API: Get security, network, location, hostname, timezone and useragent parsing.
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.
Timezone 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: Get browser, Operating System, and device info from single or multiple Useragent string parsing.

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 and reliable insights directly from the terminal.

Based on:

API version: 2.0.0

Official Release:

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

Requirements

Go 1.18+
API Key from IPGeolocation.io

Installation

1.Go install

To install ipgeolocation using go install , run:

go install github.com/IPGeolocation/cli/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 is in your PATH as well.

3.Using Download Prebuilt Binaries

I.Overview

These are prebuilt binaries for the IPGeolocation CLI tool, version 1.0.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 / Downoad Link
Linux	amd64	ipgeolocation-1.0.1-linux-amd64.tar.gz
Linux	arm64	ipgeolocation-1.0.1-linux-arm64.tar.gz
macOS	amd64	ipgeolocation-1.0.1-darwin-amd64.tar.gz
macOS	arm64	ipgeolocation-1.0.1-darwin-arm64.tar.gz
Windows	amd64	ipgeolocation-1.0.1-windows-amd64.zip

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-1.0.1-linux-amd64.tar.gz -C /usr/local/bin

Rename the binary for simplicity:

mv /usr/local/bin/ipgeolocation-1.0.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-1.0.1-darwin-amd64.tar.gz -C /usr/local/bin

Rename the binary:

mv /usr/local/bin/ipgeolocation-1.0.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-1.0.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

Note

Ensure execution permissions on Linux/macOS.
Recommended folder for binaries: /usr/local/bin or any folder in your PATH.
Prebuilt binaries include version 1.0.1 in their filename. Rename them after extraction for easier usage.
For updates, check GitHub Releases.

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.

API Plan Tiers and Documentation

The documentation below corresponds to the four available API tier plans:

Developer Plan (Free): Full Documentation
Standard Plan: Full Documentation
Advance Plan: Full Documentation
Security Plan: Full Documentation

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

Fields and commands Availability

IP Geolocation offers four plans from billing point of view: Free, Standard, Security, Advance. The availability of each command, over all plans are presented below.

Sub Command	Details	Free	Standard	Security	Advance
`config`	Set up and check API Key.
`ipgeo`	Get geolocation data for a single IP address, along with network, currency, abuse, timezone, security, asn, useragent, etc.
`bulk-ip-geo`	Get geolocation data for multiple IP addresses in a single API request, along with same data as in `ipgeo` .
`ip-security`	Get security information (VPN, TOR, proxy, etc.) for a single IP, along with network, timezone, location, and currency, etc.
`bulk-ip-security`	Get security threat intelligence for multiple IP addresses, along with same data as in `ip-security` .
`asn`	Get details of any AS number or IP address associated 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 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 single User Agent string.
`parse-bulk-user-agents`	Parse multiple User Agent String at once.

Tip

The availability of fields in every API endpoint across all API plans is provided in the Reference Table within each respective API Documentation. e.g., for IPGeolocationApi, please visit https://ipgeolocation.io/ip-location-api.html#reference-to-ipgeolocation-api-response.

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.

Tip

You can also check the version for ipgeolocation using the --version flag:

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.ipgeo Command

Lookup 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,dma,security,abuse,time_zone,user_agent` ).
`--fields`	string[]	`[]`	Return only specific fields (e.g. `location,network.asn.organization` ).
`--excludes`	string[]	`[]`	Exclude fields from output.
`--lang`	string	`""`	Response language.
`--output`	string	`pretty`	Output format: `pretty` , `raw` , `table` , `yaml` .

Note

Available language options can be found here: https://ipgeolocation.io/ip-location-api.html#response-in-multiple-languages

III.Developer Plan Examples

Get info about your current IP:

ipgeolocation ipgeo

i.Get Default Fields in developer plan

Lookup a specific IP:

ipgeolocation ipgeo --ip 8.8.8.8

Sample output:

Response

1{
2  "country_metadata": {
3    "calling_code": "+1",
4    "languages": [
5      "en-US",
6      "es-US",
7      "haw",
8      "fr"
9    ],
10    "tld": ".us"
11  },
12  "currency": {
13    "code": "USD",
14    "name": "US Dollar",
15    "symbol": "$"
16  },
17  "ip": "8.8.8.8",
18  "location": {
19    "city": "Mountain View",
20    "continent_code": "NA",
21    "continent_name": "North America",
22    "country_capital": "Washington, D.C.",
23    "country_code2": "US",
24    "country_code3": "USA",
25    "country_emoji": "🇺🇸",
26    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
27    "country_name": "United States",
28    "country_name_official": "United States of America",
29    "district": "Santa Clara",
30    "geoname_id": "6301403",
31    "is_eu": false,
32    "latitude": "37.42240",
33    "longitude": "-122.08421",
34    "state_code": "US-CA",
35    "state_prov": "California",
36    "zipcode": "94043-1351"
37  }
38}

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

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

Sample output:

Response

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.Standard Plan Examples

i.Get Default Fields in standard plan

Lookup domain name with default fields

ipgeolocation ipgeo --ip google.com

Sample output:

Response

1{
2  "country_metadata": {
3    "calling_code": "+49",
4    "languages": [
5      "de"
6    ],
7    "tld": ".de"
8  },
9  "currency": {
10    "code": "EUR",
11    "name": "Euro",
12    "symbol": "€"
13  },
14  "domain": "google.com",
15  "ip": "142.250.185.174",
16  "location": {
17    "city": "Frankfurt",
18    "continent_code": "EU",
19    "continent_name": "Europe",
20    "country_capital": "Berlin",
21    "country_code2": "DE",
22    "country_code3": "DEU",
23    "country_emoji": "🇩🇪",
24    "country_flag": "https://ipgeolocation.io/static/flags/de_64.png",
25    "country_name": "Germany",
26    "country_name_official": "Federal Republic of Germany",
27    "district": "Frankfurt",
28    "geoname_id": "6463469",
29    "is_eu": true,
30    "latitude": "50.11208",
31    "longitude": "8.68341",
32    "state_code": "DE-HE",
33    "state_prov": "Hesse",
34    "zipcode": "60311"
35  },
36  "network": {
37    "asn": {
38      "as_number": "AS15169",
39      "country": "US",
40      "organization": "Google LLC"
41    },
42    "company": {
43      "name": "Google LLC"
44    }
45  }
46}

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

1{
2  "country_metadata": {
3    "calling_code": "+230",
4    "languages": [
5      "en-MU",
6      "bho",
7      "fr"
8    ],
9    "tld": ".mu"
10  },
11  "currency": {
12    "code": "MUR",
13    "name": "Mauritius Rupee",
14    "symbol": "₨"
15  },
16  "ip": "2001:4230:4890:0:0:0:0:1",
17  "location": {
18    "city": "Quatre Bornes",
19    "continent_code": "AF",
20    "continent_name": "Afrique",
21    "country_capital": "Port Louis",
22    "country_code2": "MU",
23    "country_code3": "MUS",
24    "country_emoji": "🇲🇺",
25    "country_flag": "https://ipgeolocation.io/static/flags/mu_64.png",
26    "country_name": "Maurice",
27    "country_name_official": "",
28    "district": "Quatre Bornes",
29    "geoname_id": "1106777",
30    "is_eu": false,
31    "latitude": "-20.24304",
32    "longitude": "57.49631",
33    "state_code": "MU-PW",
34    "state_prov": "Wilhems des plaines",
35    "zipcode": "72201"
36  },
37  "network": {
38    "asn": {
39      "as_number": "AS52095",
40      "country": "CZ",
41      "organization": "Netassist International s.r.o."
42    },
43    "company": {
44      "name": "African Network Information Center AfriNIC Ltd"
45    }
46  }
47}

iii.Include HostName, Timezone and User-Agent

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

Sample output:

Response

1{
2  "country_metadata": {
3    "calling_code": "+81",
4    "languages": [
5      "ja"
6    ],
7    "tld": ".jp"
8  },
9  "currency": {
10    "code": "JPY",
11    "name": "Yen",
12    "symbol": "¥"
13  },
14  "hostname": "public-vpn-13-15.vpngate.v4.open.ad.jp",
15  "ip": "219.100.37.207",
16  "location": {
17    "city": "Tokyo",
18    "continent_code": "AS",
19    "continent_name": "Asia",
20    "country_capital": "Tokyo",
21    "country_code2": "JP",
22    "country_code3": "JPN",
23    "country_emoji": "🇯🇵",
24    "country_flag": "https://ipgeolocation.io/static/flags/jp_64.png",
25    "country_name": "Japan",
26    "country_name_official": "Japan",
27    "district": "Koto",
28    "geoname_id": "12149683",
29    "is_eu": false,
30    "latitude": "35.68467",
31    "longitude": "139.80881",
32    "state_code": "JP-13",
33    "state_prov": "Tokyo Metropolis",
34    "zipcode": "135-0022"
35  },
36  "network": {
37    "asn": {
38      "as_number": "AS36599",
39      "country": "US",
40      "organization": "SoftEther Telecommunication Research Institute, LLC"
41    },
42    "company": {
43      "name": "SoftEther Corporation"
44    }
45  },
46  "time_zone": {
47    "current_time": "2026-01-13 17:30:42.949+0900",
48    "current_time_unix": 1768293042.949,
49    "current_tz_abbreviation": "JST",
50    "current_tz_full_name": "Japan Standard Time",
51    "dst_end": {},
52    "dst_exists": false,
53    "dst_savings": 0,
54    "dst_start": {},
55    "dst_tz_abbreviation": "",
56    "dst_tz_full_name": "",
57    "is_dst": false,
58    "name": "Asia/Tokyo",
59    "offset": 9,
60    "offset_with_dst": 9,
61    "standard_tz_abbreviation": "JST",
62    "standard_tz_full_name": "Japan Standard Time"
63  }
64}

Note

The IP Geolocation API supports hostname lookup for all paid subscriptions. However, this is not included by default. To enable hostname resolution, use the --include parameter with one of the following options:

hostname : Performs a quick lookup using the internal hostname database. If no match is found, the IP is returned as-is. This is fast but may produce incomplete results.
liveHostname : Queries live sources for accurate hostname resolution. This may increase response time.
hostnameFallbackLive : Attempts the internal database first, and falls back to live sources if no result is found. This option provides a balance of speed and reliability.

V.Advanced Plan Examples

i.Include DMA, Abuse and Security

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

Sample output:

Response

1{
2  "ip": "8.8.8.8",
3  "location": {
4    "continent_code": "NA",
5    "continent_name": "North America",
6    "country_code2": "US",
7    "country_code3": "USA",
8    "country_name": "United States",
9    "country_name_official": "United States of America",
10    "country_capital": "Washington, D.C.",
11    "state_prov": "California",
12    "state_code": "US-CA",
13    "district": "Santa Clara",
14    "city": "Mountain View",
15    "zipcode": "94043-1351",
16    "latitude": "37.42240",
17    "longitude": "-122.08421",
18    "is_eu": false,
19    "geoname_id": "6301403",
20    "accuracy_radius": "25.388",
21    "locality": "Mountain View",
22    "country_emoji": "🇺🇸",
23    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
24    "dma_code": "807"
25  },
26  "country_metadata": {
27    "calling_code": "+1",
28    "tld": ".us",
29    "languages": [
30      "en-US",
31      "es-US",
32      "haw",
33      "fr"
34    ]
35  },
36  "network": {
37    "asn": {
38      "as_number": "AS15169",
39      "organization": "Google LLC",
40      "country": "US",
41      "asn_name": "GOOGLE",
42      "type": "BUSINESS",
43      "domain": "google.com",
44      "date_allocated": "",
45      "allocation_status": "",
46      "num_of_ipv4_routes": "1026",
47      "num_of_ipv6_routes": "106",
48      "rir": "ARIN"
49    },
50    "connection_type": "",
51    "company": {
52      "name": "Google LLC",
53      "type": "business",
54      "domain": "google.com"
55    }
56  },
57  "currency": {
58    "code": "USD",
59    "name": "US Dollar",
60    "symbol": "$"
61  },
62  "security": {
63    "threat_score": 0,
64    "is_tor": false,
65    "is_proxy": false,
66    "proxy_type": "",
67    "proxy_provider": "",
68    "is_anonymous": false,
69    "is_known_attacker": false,
70    "is_spam": false,
71    "is_bot": false,
72    "is_cloud_provider": false,
73    "cloud_provider": ""
74  },
75  "abuse": {
76    "route": "8.8.8.0/24",
77    "country": "",
78    "handle": "ABUSE5250-ARIN",
79    "name": "Abuse",
80    "organization": "Abuse",
81    "role": "abuse",
82    "kind": "group",
83    "address": "1600 Amphitheatre Parkway\nMountain View\nCA\n94043\nUnited States",
84    "emails": [
85      "network-abuse@google.com"
86    ],
87    "phone_numbers": [
88      "+1-650-253-0000"
89    ]
90  }
91}

Note

All features available in the Free plan are also included in the Standard and Advanced plans. Similarly, all features of the Standard plan are available in the Advanced plan.

Get only specific fields in YAML:

ipgeolocation ipgeo --ip 1.1.1.1 --fields location --output yaml

Sample response:

Response

1ip: 1.1.1.1
2location:
3    accuracy_radius: "8.778"
4    city: Hong Kong
5    confidence: high
6    continent_code: AS
7    continent_name: Asia
8    country_capital: Hong Kong
9    country_code2: HK
10    country_code3: HKG
11    country_emoji: "\U0001F1ED\U0001F1F0"
12    country_flag: https://ipgeolocation.io/static/flags/hk_64.png
13    country_name: Hong Kong
14    country_name_official: Hong Kong Special Administrative Region of the People's Republic of China
15    district: Wan Chai District
16    geoname_id: "10106797"
17    is_eu: false
18    latitude: "22.27683"
19    locality: Hong Kong
20    longitude: "114.17612"
21    state_code: ""
22    state_prov: Hong Kong SAR
23    zipcode: ""

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

3.bulk-ip-geo Command

Lookup 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 extra fields (e.g. `location,time_zone` ).
`--excludes`	string[]	`[]`	Exclude fields (e.g. `currency` ).
`--fields`	string[]	`[]`	Return only specific fields (e.g. `location` ).
`--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.

Lookup 3 IP addresses:

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

Lookup from a file:

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

Results will be written to the results.json file.

Note

All the include , exclude , fields parameters can be used just like ipgeo command.

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.

4.ip-security Command

Lookup 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.
`--include`	string[]	`[]`	Include extra fields in output. (e.g., `location,network,currency,time_zone,user_agent,country_metadata,hostname` )
`--excludes`	string[]	`[]`	Exclude fields from output.
`--fields`	string[]	`[]`	Return only specific fields (e.g. `network.asn.organization` ).
`--lang`	string	`""`	Response language.
`--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

Lookup a specific IP:

ipgeolocation ip-security --ip 8.8.8.8

Sample output:

Response

1{
2  "ip": "2.56.188.34",
3  "security": {
4    "threat_score": 80,
5    "is_tor": false,
6    "is_proxy": true,
7    "proxy_type": "VPN",
8    "proxy_provider": "Nord VPN",
9    "is_anonymous": true,
10    "is_known_attacker": true,
11    "is_spam": false,
12    "is_bot": false,
13    "is_cloud_provider": true,
14    "cloud_provider": "Packethub S.A."
15  }
16}

IV.Include Multiple Optional Fields

Lookup security information for a specific IP with including additional fields:

ipgeolocation ip-security --ip 2.56.188.34  --include location,network,currency,time_zone,user_agent,country_metadata,hostname

Output as YAML:

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

Note

You can get all the available fields in standard plan in combination with security data, when subscribed to security plan.

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

V.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

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

5.bulk-ip-security Command

Lookup 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).
`--include`	string[]	`[]`	Include extra fields (e.g. `location,network,currency,time_zone,user_agent,country_metadata,hostname` ).
`--excludes`	string[]	`[]`	Exclude fields (e.g. `currency` ).
`--fields`	string[]	`[]`	Return only specific fields (e.g. `location` ).
`--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`

III.bulk-ip-security Examples

Lookup 3 IP addresses:

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

Lookup from a file:

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

Include location and timezone:

ipgeolocation bulk-ip-security --file=ips.txt --include=location,network,time_zone

Output as YAML:

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

Save results to 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.

6.asn Command

Lookup 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, whois_response` )
`--excludes`	string[]	`[]`	Exclude fields from output.
`--fields`	string[]	`[]`	Return only specific fields (e.g. `ip,organization` ).
`--output`	string	`pretty`	Output format: `pretty` , `raw` , `table` , `yaml` .

Note

ASN API is only available in the Advanced Plan

III.Get ASN Information of your IP

Get ASN information about your current IP address:

ipgeolocation asn

IV.Get ASN Information by ASN Number

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

ipgeolocation asn --asn 15169

Sample output:

Response

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

Lookup a specific IP with including additional fields:

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

Sample output:

Response

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

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.

7.abuse Command

Lookup 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.
`--excludes`	string[]	`[]`	Exclude fields from output.
`--fields`	string[]	`[]`	Return only specific fields (e.g. `ip,organization` ).
`--output`	string	`pretty`	Output format: `pretty` , `raw` , `table` , `yaml` .

Note

Abuse Contact API is only available in the Advanced Plan

III.Get abuse info about your current IP

ipgeolocation abuse

IV.Lookup a specific IP

ipgeolocation abuse --ip 8.8.8.8

V.Exclude unnecessary fields

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

VI.Lookup Abuse Contact with Specific Fields

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

Sample output:

Response

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

Get output as YAML:

ipgeolocation abuse --ip 8.8.8.8 --output=yaml

Sample output:

Response

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    handle: ABUSE5250-ARIN
12    kind: group
13    name: Abuse
14    organization: Abuse
15    phone_numbers:
16        - +1-650-253-0000
17    role: abuse
18    route: 8.8.8.0/24
19ip: 8.8.8.8

For further information, please visit Abuse API Documentation.

8.timezone Command

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

For full API specifications, refer to the Timezone 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

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_tz_abbreviation": "PST",
21    "current_tz_full_name": "Pacific Standard Time",
22    "date": "2026-01-13",
23    "date_time": "2026-01-13 04:10:37",
24    "date_time_txt": "Tuesday, January 13, 2026 04:10:37",
25    "date_time_unix": 1768306237.124,
26    "date_time_wti": "Tue, 13 Jan 2026 04:10:37 -0800",
27    "date_time_ymd": "2026-01-13T04:10:37-0800",
28    "dst_end": {
29      "date_time_after": "2026-11-01 TIME 01",
30      "date_time_before": "2026-11-01 TIME 02",
31      "duration": "-1H",
32      "gap": false,
33      "overlap": true,
34      "utc_time": "2026-11-01 TIME 09"
35    },
36    "dst_exists": true,
37    "dst_savings": 0,
38    "dst_start": {
39      "date_time_after": "2026-03-08 TIME 03",
40      "date_time_before": "2026-03-08 TIME 02",
41      "duration": "+1H",
42      "gap": true,
43      "overlap": false,
44      "utc_time": "2026-03-08 TIME 10"
45    },
46    "dst_tz_abbreviation": "PDT",
47    "dst_tz_full_name": "Pacific Daylight Time",
48    "is_dst": false,
49    "month": 1,
50    "name": "America/Los_Angeles",
51    "offset": -8,
52    "offset_with_dst": -8,
53    "standard_tz_abbreviation": "PST",
54    "standard_tz_full_name": "Pacific Standard Time",
55    "time_12": "04:10:37 AM",
56    "time_24": "04:10:37",
57    "week": 3,
58    "year": 2026,
59    "year_abbr": "26"
60  }
61}

V.Get Timezone by Timezone Name

ipgeolocation timezone --tz America/New_York

Sample output:

Response

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

VI.Get Timezone from Any Address

ipgeolocation timezone --location "New York, USA"

Sample output:

Response

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_tz_abbreviation": "EST",
13    "current_tz_full_name": "Eastern Standard Time",
14    "date": "2026-01-13",
15    "date_time": "2026-01-13 07:14:38",
16    "date_time_txt": "Tuesday, January 13, 2026 07:14:38",
17    "date_time_unix": 1768306478.948,
18    "date_time_wti": "Tue, 13 Jan 2026 07:14:38 -0500",
19    "date_time_ymd": "2026-01-13T07:14:38-0500",
20    "dst_end": {
21      "date_time_after": "2026-11-01 TIME 01",
22      "date_time_before": "2026-11-01 TIME 02",
23      "duration": "-1H",
24      "gap": false,
25      "overlap": true,
26      "utc_time": "2026-11-01 TIME 06"
27    },
28    "dst_exists": true,
29    "dst_savings": 0,
30    "dst_start": {
31      "date_time_after": "2026-03-08 TIME 03",
32      "date_time_before": "2026-03-08 TIME 02",
33      "duration": "+1H",
34      "gap": true,
35      "overlap": false,
36      "utc_time": "2026-03-08 TIME 07"
37    },
38    "dst_tz_abbreviation": "EDT",
39    "dst_tz_full_name": "Eastern Daylight Time",
40    "is_dst": false,
41    "month": 1,
42    "name": "America/New_York",
43    "offset": -5,
44    "offset_with_dst": -5,
45    "standard_tz_abbreviation": "EST",
46    "standard_tz_full_name": "Eastern Standard Time",
47    "time_12": "07:14:38 AM",
48    "time_24": "07:14:38",
49    "week": 3,
50    "year": 2026,
51    "year_abbr": "26"
52  }
53}

VII.Get Timezone from Location Coordinates

ipgeolocation timezone --latitude 37.7749 --longitude -122.4194

Sample output:

Response

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

VIII.Get Timezone and Airport Details from IATA Code

ipgeolocation timezone --iata DXB

Sample output:

Response

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_tz_abbreviation": "GST",
18    "current_tz_full_name": "Gulf Standard Time",
19    "date": "2026-01-13",
20    "date_time": "2026-01-13 16:16:46",
21    "date_time_txt": "Tuesday, January 13, 2026 16:16:46",
22    "date_time_unix": 1768306606.662,
23    "date_time_wti": "Tue, 13 Jan 2026 16:16:46 +0400",
24    "date_time_ymd": "2026-01-13T16:16:46+0400",
25    "dst_end": {},
26    "dst_exists": false,
27    "dst_savings": 0,
28    "dst_start": {},
29    "dst_tz_abbreviation": "",
30    "dst_tz_full_name": "",
31    "is_dst": false,
32    "month": 1,
33    "name": "Asia/Dubai",
34    "offset": 4,
35    "offset_with_dst": 4,
36    "standard_tz_abbreviation": "GST",
37    "standard_tz_full_name": "Gulf Standard Time",
38    "time_12": "04:16:46 PM",
39    "time_24": "16:16:46",
40    "week": 3,
41    "year": 2026,
42    "year_abbr": "26"
43  }
44}

Note

Similarly, you can fetch Airport Details and Timezone from using any ICAO code as well.

IX.Get Timezone and City Details from UN/LOCODE

ipgeolocation timezone --lo DEBER

Sample ouput:

Response

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_tz_abbreviation": "CET",
14    "current_tz_full_name": "Central European Standard Time",
15    "date": "2026-01-13",
16    "date_time": "2026-01-13 13:18:15",
17    "date_time_txt": "Tuesday, January 13, 2026 13:18:15",
18    "date_time_unix": 1768306695.348,
19    "date_time_wti": "Tue, 13 Jan 2026 13:18:15 +0100",
20    "date_time_ymd": "2026-01-13T13:18:15+0100",
21    "dst_end": {
22      "date_time_after": "2026-10-25 TIME 02",
23      "date_time_before": "2026-10-25 TIME 03",
24      "duration": "-1H",
25      "gap": false,
26      "overlap": true,
27      "utc_time": "2026-10-25 TIME 01"
28    },
29    "dst_exists": true,
30    "dst_savings": 0,
31    "dst_start": {
32      "date_time_after": "2026-03-29 TIME 03",
33      "date_time_before": "2026-03-29 TIME 02",
34      "duration": "+1H",
35      "gap": true,
36      "overlap": false,
37      "utc_time": "2026-03-29 TIME 01"
38    },
39    "dst_tz_abbreviation": "CEST",
40    "dst_tz_full_name": "Central European Summer Time",
41    "is_dst": false,
42    "month": 1,
43    "name": "Europe/Berlin",
44    "offset": 1,
45    "offset_with_dst": 1,
46    "standard_tz_abbreviation": "CET",
47    "standard_tz_full_name": "Central European Standard Time",
48    "time_12": "01:18:15 PM",
49    "time_24": "13:18:15",
50    "week": 3,
51    "year": 2026,
52    "year_abbr": "26"
53  }
54}

Output as YAML:

ipgeolocation timezone --ip 8.8.8.8 --output=yaml

9.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 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

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}

Note

You can convert time from any timezone to another timezone using location coordinates (Latitude and Longitude), location addresses, IATA codes, ICAO codes and UN/LUCODE.

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:

ipgeolocation time-conversion --icao_from KATL --icao_to EWR

Convert from one LO code to another:

ipgeolocation time-conversion --lo_from DEBER --lo_to JFK

Output as YAML:

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

10.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
Timezone-based or coordinate-based location support

You can specify the location using IP, city name, coordinates, or timezone.

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	`""`	Timezone.
`--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

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

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

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}

11.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
Timezone-based or coordinate-based location support

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` .

Note

The start-date and end-date flags are required.
The start-date and end-date should be in YYYY-MM-DD format.
The start-date and end-date should be less than 90 days.

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

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}

12.parse-user-agent Command

The parse-user-agent command uses the ipgeolocation.io User Agent Parser 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 Parser 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

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}

13.parse-bulk-user-agents Command

The parse-bulk-user-agents command uses the ipgeolocation.io Bulk User-Agent Parser 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 Bulk User Agent Parser API Documentation.

Note

The user-agents flag is required.
The user-agents flag should be an array of user agent strings.

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

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.