IP Query Documentation

A Go-based service for querying geographic location information by IP address.

The project does not include database files. You need to download the required database from lite.ip2location.com.

• Simple REST API endpoint
• Returns detailed location information, including country, region, and city
• Easy to set up and run

1. Clone the repository:

   git clone <repository-url>
   cd ipquery

2. Install dependencies:

   go mod tidy

3. Run the service:

   go run .

The service will start running on http://localhost:8080.

There are two ways to use the service:

Query location information by making a GET request to the /query endpoint.

• If no api_key is specified, the API request only requires the IP address.
• If an api_key environment variable is set, the API request must include a sign (signature) and time (timestamp) in addition to the IP address.
• Alternatively, set the environment variable IPQUERY_API_KEY=xxxx.

Start the service:

ipquery -port :80 -db_path ./IP2LOCATION-LITE-DB3.BIN

Or with an API key:

ipquery -api_key=xxx -port :80 -db_path ./IP2LOCATION-LITE-DB3.BIN

Make API requests:

curl "http://localhost:8080/query?ip=202.106.0.20"
curl "http://localhost:8080/query?ip=202.106.0.20&sign=xxx&time=2020303434"

ipquery -query 202.106.0.20

The service returns location data in JSON format:

[
  {
    "ip": "202.106.0.20",
    "country": "China",
    "country_code": "CN",
    "region": "Beijing",
    "city": "Beijing"
  }
]

• ip: The queried IP address
• country: Country name
• country_code: Two-letter country code (ISO 3166-1 alpha-2)
• region: Region or province name
• city: City name

GET /query?ip=<ip_address>

• Parameters:

  • ip (required): The IP address to query (IPv4 format). Multiple IPs can be separated by commas, returning an array of location objects.

• Response: A JSON object containing location information. For multiple IPs, an array of location objects is returned.

Examples:

• Single IP request:

  /query?ip=34.32.23.12
  

  {"ip":"34.32.23.12","country":"Germany","country_code":"DE","region":"Berlin","city":"Berlin"}

• Multiple IP request:

  /query?ip=34.32.23.12,34.32.23.13
  

  [
    {"ip":"34.32.23.12","country":"Germany","country_code":"DE","region":"Berlin","city":"Berlin"},
    {"ip":"34.32.23.13","country":"Germany","country_code":"DE","region":"Berlin","city":"Berlin"}
  ]

To build the application:

go build -o ipquery

Run the service with a container:

podman run --rm -it -p 8080:8080 -v ./IP2LOCATION-LITE-DB3.BIN:/app/IP2LOCATION-LITE-DB3.BIN javyliu/ipquery:v1.0.1

To specify an IPQUERY_API_KEY environment variable:

podman run --rm -it -p 8080:8080 -v ./IP2LOCATION-LITE-DB3.BIN:/app/IP2LOCATION-LITE-DB3.BIN -e IPQUERY_API_KEY=xxxx javyliu/ipquery:v1.0.1

You can specify the -locale option at startup; the default is zh-CN.

ipquery -locale=zh-CN

The corresponding localization file is zh-CN.json:

{
  "countries": { "US": "美国", "CN": "中国" },
  "regions": { "CA": "加利福尼亚", "BJ": "北京" },
  "cities": { "Los Angeles": "洛杉矶", "Beijing": "北京" }
}

IpQuery is released under the MIT License.