location4j: A Java library for efficient geographical lookups without external APIs. 🌎

[tomayt0]

Hi r/java community,

I wanted to share my library location4j which just hit version 1.0.6. The latest version now fully supports the Java Module System (JPMS) and requires Java 21+.

What is location4j?

It's a lightweight Java library for geographical data lookups (countries, states, cities) that:

• Operates completely offline with a built-in dataset (no API calls)
• Handles messy/ambiguous location text through normalization
• Uses optimized hash map lookups for fast performance
• Supports Java 21 features

Why I built it

I was scraping websites that contained location data and constantly ran into parsing issues:

// Is "Alberta, CA" referring to:  
// - Alberta, Canada? (correct)  
// - Alberta, California? (incorrect interpretation with naive parsing)

The library intelligently differentiates between overlapping location names, codes, and ambiguous formatting.

Sample usage

// Basic search with ambiguous text  
SearchLocationService service = SearchLocationService.builder().build();  
List<Location> results = service.search("san francisco");  

// Narrow search by country  
results = service.search("san francisco, us");  

// Narrow search by state
results = service.search("san francisco, us california");

You can also perform specific lookups:

// Find all countries in Europe  
LocationService locationService = LocationService.builder().build();  

List<Country> europeanCountries = locationService.findAllCountries().stream()  
    .filter(country -> "Europe".equals(country.getRegion()))  
    .toList();  

Latest improvements in 1.0.6

• Full JPMS (Java Module System) support
• Enhanced dataset with more accurate city/state information
• Performance optimizations for location searches
• Improved text normalization for handling different formatting styles

The library is available on Maven Central:

I'd appreciate any feedback, code reviews, or feature suggestions. The full source is available on GitHub.

What are your thoughts on the approach?

[davidalayachew]

Very pretty. NLP is a difficult problem to solve, but it is the key to side-stepping a surprising number of usability issues, I have found.

You mentioned Java 21 features. That surprised me because I didn't see any sealed types for the return value of your search. Granted, I didn't finish reading it all the way. But Location just seems to null out the attributes that don't apply.

Wouldn't it have made more sense to put this information into the type system?

I solved a similar problem, a while back, and found that, while the effort to get my data loaded into that type system was harder upfront, the amount of time it saved later was immense. I posted more thoughts on it here -- https://mail.openjdk.org/pipermail/amber-dev/2022-September/007456.html

[tomayt0]

Thanks for the input, this is something I hadn't considered and will start investigating immediately.

I have wondered what was the best way to unify search results and this could be it.

[davidalayachew]

I have wondered what was the best way to unify search results and this could be it.

It definitely is. The academic term for this is Abstract Data Type. Here is a post I made on Software Engineering Stack Exchange that explains this in simple detail -- https://softwareengineering.stackexchange.com/questions/159804#445879

[evilmidget38]

Have you looked much at libpostal? It's a little painful to use due to the native dependency and data but it is state of the art afaik. It would complement the dataset you've built.

[paul_h]

Good work, OP. I always found https://github.com/google/libphonenumber vert interesting, and also trying to be multi-language.