Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# CLAUDE.md - GeoIP2 Java API
# CLAUDE.md - GeoIP Java API

This document contains guidance for Claude (and other AI assistants) when working with the GeoIP2-java codebase. It captures architectural patterns, conventions, and lessons learned to help maintain consistency and quality.

## Project Overview

**GeoIP2-java** is MaxMind's official Java client library for:
- **GeoIP2/GeoLite2 Web Services**: Country, City, and Insights endpoints
- **GeoIP2/GeoLite2 Databases**: Local MMDB file reading for various database types (City, Country, ASN, Anonymous IP, ISP, etc.)
- **GeoIP/GeoLite Web Services**: Country, City Plus, and Insights endpoints
- **GeoIP/GeoLite Databases**: Local MMDB file reading for various database types (City, Country, ASN, Anonymous IP, ISP, etc.)

The library provides both web service clients and database readers that return strongly-typed model objects containing geographic, ISP, anonymizer, and other IP-related data.

Expand Down Expand Up @@ -397,7 +397,7 @@ public interface JsonSerializable {
## Additional Resources

- [API Documentation](https://maxmind.github.io/GeoIP2-java/)
- [GeoIP2 Web Services Docs](https://dev.maxmind.com/geoip/docs/web-services)
- [GeoIP Web Services Docs](https://dev.maxmind.com/geoip/docs/web-services)
- [MaxMind DB Format](https://maxmind.github.io/MaxMind-DB/)
- GitHub Issues: https://github.com/maxmind/GeoIP2-java/issues

Expand Down
50 changes: 25 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# GeoIP2 Java API #
# GeoIP Java API #

## Description ##

This distribution provides an API for the GeoIP2 and GeoLite2 [web
This distribution provides an API for the GeoIP and GeoLite [web
services](https://dev.maxmind.com/geoip/docs/web-services?lang=en) and
[databases](https://dev.maxmind.com/geoip/docs/databases?lang=en).

Expand Down Expand Up @@ -43,16 +43,16 @@ file and its dependencies in your classpath. Download the JAR files from the
## IP Geolocation Usage ##

IP geolocation is inherently imprecise. Locations are often near the center of
the population. Any location provided by a GeoIP2 database or web service
the population. Any location provided by a GeoIP database or web service
should not be used to identify a particular address or household.

## Web Service Usage ##

To use the web service API, you must create a new `WebServiceClient` using the
`WebServiceClient.Builder`. You must provide the `Builder` constructor your
MaxMind `accountId` and `licenseKey`. To use the GeoLite2 web services instead
of GeoIP2, set the `host` method on the builder to `geolite.info`. To use
the Sandbox GeoIP2 web services instead of the production GeoIP2 web
MaxMind `accountId` and `licenseKey`. To use the GeoLite web services instead
of GeoIP, set the `host` method on the builder to `geolite.info`. To use
the Sandbox GeoIP web services instead of the production GeoIP web
services, set the `host` method on the builder to `sandbox.maxmind.com`.
You may also set a `timeout` or set the `locales` fallback order using the
methods on the `Builder`. After you have created the `WebServiceClient`,
Expand Down Expand Up @@ -122,10 +122,10 @@ before any intermediary does so.
// connections alive for future requests.
//
// Replace "42" with your account ID and "license_key" with your license key.
// To use the GeoLite2 web service instead of the GeoIP2 web service, call the
// To use the GeoLite web service instead of the GeoIP web service, call the
// host method on the builder with "geolite.info", e.g.
// new WebServiceClient.Builder(42, "license_key").host("geolite.info").build()
// To use the Sandbox GeoIP2 web service instead of the production GeoIP2
// To use the Sandbox GeoIP web service instead of the production GeoIP
// web service, call the host method on the builder with
// "sandbox.maxmind.com", e.g.
// new WebServiceClient.Builder(42, "license_key").host("sandbox.maxmind.com").build()
Expand All @@ -151,10 +151,10 @@ System.out.println(country.names().get("zh-CN")); // '美国'
// connections alive for future requests.
//
// Replace "42" with your account ID and "license_key" with your license key.
// To use the GeoLite2 web service instead of the GeoIP2 web service, call the
// To use the GeoLite web service instead of the GeoIP web service, call the
// host method on the builder with "geolite.info", e.g.
// new WebServiceClient.Builder(42, "license_key").host("geolite.info").build()
// To use the Sandbox GeoIP2 web service instead of the production GeoIP2
// To use the Sandbox GeoIP web service instead of the production GeoIP
// web service, call the host method on the builder with
// "sandbox.maxmind.com", e.g.
// new WebServiceClient.Builder(42, "license_key").host("sandbox.maxmind.com").build()
Expand Down Expand Up @@ -194,8 +194,8 @@ System.out.println(location.longitude()); // -93.2323
// connections alive for future requests.
//
// Replace "42" with your account ID and "license_key" with your license key.
// Please note that the GeoLite2 web service does not support Insights.
// To use the Sandbox GeoIP2 web service instead of the production GeoIP2
// Please note that the GeoLite web service does not support Insights.
// To use the Sandbox GeoIP web service instead of the production GeoIP
// web service, call the host method on the builder with
// "sandbox.maxmind.com", e.g.
// new WebServiceClient.Builder(42, "license_key").host("sandbox.maxmind.com").build()
Expand Down Expand Up @@ -239,7 +239,7 @@ System.out.println(response.traits().userType()); // 'college'

To use the database API, you must create a new `DatabaseReader` using the
`DatabaseReader.Builder`. You must provide the `Builder` constructor either an
`InputStream` or `File` for your GeoIP2 database. You may also specify the
`InputStream` or `File` for your GeoIP database. You may also specify the
`fileMode` and the `locales` fallback order using the methods on the `Builder`
object.

Expand All @@ -254,7 +254,7 @@ method will be slightly faster as they do not need to construct and throw
an exception. These methods otherwise behave the same.

If the lookup succeeds, the method call will return a response class for the
GeoIP2 lookup. The class in turn contains multiple record classes, each of
GeoIP lookup. The class in turn contains multiple record classes, each of
which represents part of the data returned by the database.

We recommend reusing the `DatabaseReader` object rather than creating a new
Expand Down Expand Up @@ -291,7 +291,7 @@ thrown when querying the database.
### City ###

```java
// A File object pointing to your GeoIP2 or GeoLite2 database
// A File object pointing to your GeoIP or GeoLite database
File database = new File("/path/to/GeoIP2-City.mmdb");

// This creates the DatabaseReader object. To improve performance, reuse
Expand Down Expand Up @@ -327,7 +327,7 @@ try (DatabaseReader reader = new DatabaseReader.Builder(database).build()) {
### Anonymous IP ###

```java
// A File object pointing to your GeoIP2 Anonymous IP database
// A File object pointing to your GeoIP Anonymous IP database
File database = new File("/path/to/GeoIP2-Anonymous-IP.mmdb");

// This creates the DatabaseReader object. To improve performance, reuse
Expand All @@ -349,7 +349,7 @@ try (DatabaseReader reader = new DatabaseReader.Builder(database).build()) {
### Anonymous Plus ###

```java
// A File object pointing to your GeoIP2 Anonymous Plus database
// A File object pointing to your GeoIP Anonymous Plus database
File database = new File("/path/to/GeoIP-Anonymous-Plus.mmdb");

// This creates the DatabaseReader object. To improve performance, reuse
Expand All @@ -374,7 +374,7 @@ try (DatabaseReader reader = new DatabaseReader.Builder(database).build()) {
### ASN ###

```java
// A File object pointing to your GeoLite2 ASN database
// A File object pointing to your GeoLite ASN database
File database = new File("/path/to/GeoLite2-ASN.mmdb");

// This creates the DatabaseReader object. To improve performance, reuse
Expand All @@ -393,7 +393,7 @@ try (DatabaseReader reader = new DatabaseReader.Builder(database).build()) {
### Connection-Type ###

```java
// A File object pointing to your GeoIP2 Connection-Type database
// A File object pointing to your GeoIP Connection-Type database
File database = new File("/path/to/GeoIP2-Connection-Type.mmdb");

// This creates the DatabaseReader object. To improve performance, reuse
Expand All @@ -413,7 +413,7 @@ try (DatabaseReader reader = new DatabaseReader.Builder(database).build()) {
### Domain ###

```java
// A File object pointing to your GeoIP2 Domain database
// A File object pointing to your GeoIP Domain database
File database = new File("/path/to/GeoIP2-Domain.mmdb");

// This creates the DatabaseReader object. To improve performance, reuse
Expand All @@ -430,7 +430,7 @@ try (DatabaseReader reader = new DatabaseReader.Builder(database).build()) {
### Enterprise ###

```java
// A File object pointing to your GeoIP2 Enterprise database
// A File object pointing to your GeoIP Enterprise database
File database = new File("/path/to/GeoIP2-Enterprise.mmdb");

// This creates the DatabaseReader object. To improve performance, reuse
Expand Down Expand Up @@ -470,7 +470,7 @@ try (DatabaseReader reader = new DatabaseReader.Builder(database).build()) {
### ISP ###

```java
// A File object pointing to your GeoIP2 ISP database
// A File object pointing to your GeoIP ISP database
File database = new File("/path/to/GeoIP2-ISP.mmdb");

// This creates the DatabaseReader object. To improve performance, reuse
Expand All @@ -490,7 +490,7 @@ try (DatabaseReader reader = new DatabaseReader.Builder(database).build()) {
## Exceptions ##

For details on the possible errors returned by the web service itself, [see
the GeoIP2 web service
the GeoIP web service
documentation](https://dev.maxmind.com/geoip/docs/web-services?lang=en).

If the web service returns an explicit error document, this is thrown as an
Expand Down Expand Up @@ -550,7 +550,7 @@ databases with data on geographical features around the world, including
populated places. They offer both free and paid premium data. Each
feature is uniquely identified by a `geonameId`, which is an integer.

Many of the records returned by the GeoIP2 web services and databases
Many of the records returned by the GeoIP web services and databases
include a `geonameId()` method. This is the ID of a geographical
feature (city, region, country, etc.) in the GeoNames database.

Expand Down Expand Up @@ -596,7 +596,7 @@ whenever possible.

## Versioning ##

The GeoIP2 Java API uses [Semantic Versioning](https://semver.org/).
The GeoIP Java API uses [Semantic Versioning](https://semver.org/).

## Copyright and License ##

Expand Down
2 changes: 1 addition & 1 deletion docs/hugo.toml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
title = "GeoIP2 Java API"
title = "GeoIP Java API"
disableKinds = ["taxonomy", "term", "RSS"]

[[cascade]]
Expand Down
4 changes: 2 additions & 2 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@
<artifactId>geoip2</artifactId>
<version>5.1.0</version>
<packaging>jar</packaging>
<name>MaxMind GeoIP2 API</name>
<description>GeoIP2 webservice client and database reader</description>
<name>MaxMind GeoIP API</name>
<description>GeoIP webservice client and database reader</description>
<url>https://dev.maxmind.com/geoip?lang=en</url>
<licenses>
<license>
Expand Down
34 changes: 17 additions & 17 deletions src/main/java/com/maxmind/geoip2/DatabaseProvider.java
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
import java.util.Optional;

/**
* Interface for GeoIP2 database providers.
* Interface for GeoIP database providers.
*/
public interface DatabaseProvider extends GeoIp2Provider {

Expand All @@ -39,7 +39,7 @@ Optional<CityResponse> tryCity(InetAddress ipAddress) throws IOException,
GeoIp2Exception;

/**
* Look up an IP address in a GeoIP2 Anonymous IP.
* Look up an IP address in a GeoIP Anonymous IP.
*
* @param ipAddress IPv4 or IPv6 address to lookup.
* @return a AnonymousIpResponse for the requested IP address.
Expand All @@ -50,7 +50,7 @@ AnonymousIpResponse anonymousIp(InetAddress ipAddress) throws IOException,
GeoIp2Exception;

/**
* Look up an IP address in a GeoIP2 Anonymous IP.
* Look up an IP address in a GeoIP Anonymous IP.
*
* @param ipAddress IPv4 or IPv6 address to lookup.
* @return a AnonymousIpResponse for the requested IP address or empty if it is not in the DB.
Expand All @@ -61,7 +61,7 @@ Optional<AnonymousIpResponse> tryAnonymousIp(InetAddress ipAddress) throws IOExc
GeoIp2Exception;

/**
* Look up an IP address in a GeoIP2 Anonymous Plus.
* Look up an IP address in a GeoIP Anonymous Plus.
*
* @param ipAddress IPv4 or IPv6 address to lookup.
* @return a AnonymousPlusResponse for the requested IP address.
Expand All @@ -72,7 +72,7 @@ AnonymousPlusResponse anonymousPlus(InetAddress ipAddress) throws IOException,
GeoIp2Exception;

/**
* Look up an IP address in a GeoIP2 Anonymous Plus.
* Look up an IP address in a GeoIP Anonymous Plus.
*
* @param ipAddress IPv4 or IPv6 address to lookup.
* @return a AnonymousPlusResponse for the requested IP address or empty if it is not in the DB.
Expand All @@ -83,7 +83,7 @@ Optional<AnonymousPlusResponse> tryAnonymousPlus(InetAddress ipAddress) throws I
GeoIp2Exception;

/**
* Look up an IP address in a GeoIP2 IP Risk database.
* Look up an IP address in a GeoIP IP Risk database.
*
* @param ipAddress IPv4 or IPv6 address to lookup.
* @return an IpRiskResponse for the requested IP address.
Expand All @@ -94,7 +94,7 @@ IpRiskResponse ipRisk(InetAddress ipAddress) throws IOException,
GeoIp2Exception;

/**
* Look up an IP address in a GeoIP2 IP Risk database.
* Look up an IP address in a GeoIP IP Risk database.
*
* @param ipAddress IPv4 or IPv6 address to lookup.
* @return an IPRiskResponse for the requested IP address or empty if it is not in the DB.
Expand All @@ -105,7 +105,7 @@ Optional<IpRiskResponse> tryIpRisk(InetAddress ipAddress) throws IOException,
GeoIp2Exception;

/**
* Look up an IP address in a GeoLite2 ASN database.
* Look up an IP address in a GeoLite ASN database.
*
* @param ipAddress IPv4 or IPv6 address to lookup.
* @return an IspResponse for the requested IP address.
Expand All @@ -116,7 +116,7 @@ AsnResponse asn(InetAddress ipAddress) throws IOException,
GeoIp2Exception;

/**
* Look up an IP address in a GeoLite2 ASN database.
* Look up an IP address in a GeoLite ASN database.
*
* @param ipAddress IPv4 or IPv6 address to lookup.
* @return an IspResponse for the requested IP address or empty if it is not in the DB.
Expand All @@ -127,7 +127,7 @@ Optional<AsnResponse> tryAsn(InetAddress ipAddress) throws IOException,
GeoIp2Exception;

/**
* Look up an IP address in a GeoIP2 Connection Type database.
* Look up an IP address in a GeoIP Connection Type database.
*
* @param ipAddress IPv4 or IPv6 address to lookup.
* @return a ConnectTypeResponse for the requested IP address.
Expand All @@ -138,7 +138,7 @@ ConnectionTypeResponse connectionType(InetAddress ipAddress)
throws IOException, GeoIp2Exception;

/**
* Look up an IP address in a GeoIP2 Connection Type database.
* Look up an IP address in a GeoIP Connection Type database.
*
* @param ipAddress IPv4 or IPv6 address to lookup.
* @return a ConnectTypeResponse for the requested IP address or empty if it is not in the DB.
Expand All @@ -149,7 +149,7 @@ Optional<ConnectionTypeResponse> tryConnectionType(InetAddress ipAddress)
throws IOException, GeoIp2Exception;

/**
* Look up an IP address in a GeoIP2 Domain database.
* Look up an IP address in a GeoIP Domain database.
*
* @param ipAddress IPv4 or IPv6 address to lookup.
* @return a DomainResponse for the requested IP address.
Expand All @@ -160,7 +160,7 @@ DomainResponse domain(InetAddress ipAddress) throws IOException,
GeoIp2Exception;

/**
* Look up an IP address in a GeoIP2 Domain database.
* Look up an IP address in a GeoIP Domain database.
*
* @param ipAddress IPv4 or IPv6 address to lookup.
* @return a DomainResponse for the requested IP address or empty if it is not in the DB.
Expand All @@ -171,7 +171,7 @@ Optional<DomainResponse> tryDomain(InetAddress ipAddress) throws IOException,
GeoIp2Exception;

/**
* Look up an IP address in a GeoIP2 Enterprise database.
* Look up an IP address in a GeoIP Enterprise database.
*
* @param ipAddress IPv4 or IPv6 address to lookup.
* @return an EnterpriseResponse for the requested IP address.
Expand All @@ -182,7 +182,7 @@ EnterpriseResponse enterprise(InetAddress ipAddress) throws IOException,
GeoIp2Exception;

/**
* Look up an IP address in a GeoIP2 Enterprise database.
* Look up an IP address in a GeoIP Enterprise database.
*
* @param ipAddress IPv4 or IPv6 address to lookup.
* @return an EnterpriseResponse for the requested IP address or empty if it is not in the DB.
Expand All @@ -193,7 +193,7 @@ Optional<EnterpriseResponse> tryEnterprise(InetAddress ipAddress) throws IOExcep
GeoIp2Exception;

/**
* Look up an IP address in a GeoIP2 ISP database.
* Look up an IP address in a GeoIP ISP database.
*
* @param ipAddress IPv4 or IPv6 address to lookup.
* @return an IspResponse for the requested IP address.
Expand All @@ -204,7 +204,7 @@ IspResponse isp(InetAddress ipAddress) throws IOException,
GeoIp2Exception;

/**
* Look up an IP address in a GeoIP2 ISP database.
* Look up an IP address in a GeoIP ISP database.
*
* @param ipAddress IPv4 or IPv6 address to look up or empty if it is not in the DB.
* @return an IspResponse for the requested IP address.
Expand Down
Loading
Loading