https://github.com/tomaytotomato/location4j
A Java library for efficient geographical lookups without external APIs. 🌎 Provides country, state, and city identification from free text with a built-in dataset.
https://github.com/tomaytotomato/location4j
city country country-codes country-data country-list geolocation geolocation-api geolocator java latitude-longitude location location-lookup location-search location-services lookup search state
Last synced: about 1 year ago
JSON representation
A Java library for efficient geographical lookups without external APIs. 🌎 Provides country, state, and city identification from free text with a built-in dataset.
- Host: GitHub
- URL: https://github.com/tomaytotomato/location4j
- Owner: tomaytotomato
- License: mit
- Created: 2024-07-17T11:02:50.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2025-03-21T18:30:31.000Z (about 1 year ago)
- Last Synced: 2025-03-26T13:53:53.792Z (about 1 year ago)
- Topics: city, country, country-codes, country-data, country-list, geolocation, geolocation-api, geolocator, java, latitude-longitude, location, location-lookup, location-search, location-services, lookup, search, state
- Language: Java
- Homepage: https://javadoc.io/doc/com.tomaytotomato/location4j
- Size: 10.7 MB
- Stars: 52
- Watchers: 2
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# location4j 🌎4️⃣♨️
[](https://sonarcloud.io/summary/new_code?id=tomaytotomato_location4j)
[](https://sonarcloud.io/summary/new_code?id=tomaytotomato_location4j)
[](https://javadoc.io/doc/com.tomaytotomato/location4j/1.0.6)
[](https://libs.tech/project/829971910/location4j)
location4j is a simple Java library designed for efficient and accurate geographical data lookups
for countries, states, and cities. 🗺️
Unlike other libraries, it operates without relying on third-party APIs, making it both
cost-effective and fast. 🏎️
Its built-in dataset provides quick lookups and no need for external HTTP calls. 📀
## Requirements 📋
- Java 21 or higher (uses JPMS and Java 21 features)
- Maven 3.8+ (for building from source)
## Setup 🚀
Get the latest version of the location4j library by adding it to your Maven pom.xml
```xml
com.tomaytotomato
location4j
1.0.6
```
**Gradle**
```gradle
implementation group: 'com.tomaytotomato', name: 'location4j', version: '1.0.6'
```
## Quick Example 🏗
```java
import com.tomaytotomato.location4j.SearchLocationService;
public class Main {
public static void main(String[] args) {
SearchLocationService searchLocationService = SearchLocationService.builder().build();
// Find all locations named San Francisco
List results = searchLocationService.search("san francisco");
printResults(results);
// Narrow search to the US
results = searchLocationService.search("san francisco, us");
printResults(results);
// Narrow search further to California
results = searchLocationService.search("san francisco, us california");
printResults(results);
}
private static void printResults(List results) {
System.out.println("Locations found: " + results.size());
results.forEach(location -> {
System.out.println("Country: " + location.getCountryName());
System.out.println("State: " + location.getStateName());
System.out.println("City: " + location.getCityName());
});
}
}
```
## Features 🔬
| Feature | Supported | Object | Example |
|--------------------------------------------|-----------|----------|---------------------------------------------------------------------------------|
| Search (free text) | ✅ | Location | `search("kyiv")` -> `"Kyiv, Ukraine, Europe, UA"` |
| Find All Countries | ✅ | Country | `findAllCountries()` -> `["Belgium", "Canada", ...]` |
| Find Country by Id | ✅ | Country | `findCountryById(1)` -> `["Afghanistan"]` |
| Find Country by ISO2 code | ✅ | Country | `findCountryByISO2Code("CA")` -> `["Canada"]` |
| Find Country by ISO3 code | ✅ | Country | `findCountryByISO3Code("CAN")` -> `["Canada"]` |
| Find Country by Name | ✅ | Country | `findCountryByName("Canada")` -> `["Canada"]` |
| Find Country by Localised name | ✅ | Country | `findCountryByLocalisedName("Belgique")` -> `["Belgium"]` |
| Find Countries by State name | ✅ | Country | `findAllCountriesByStateName("Texas")` -> `["USA"]` |
| Find States by State name | ✅ | State | `findAllStatesByStateName("Texas")` -> `["Texas", "USA"]` |
| Find State by State Id | ✅ | State | `findStateById(5)` -> `["California", "USA"]` |
| Find States by State code | ✅ | State | `findAllStatesByStateCode("CA")` -> `["California", "USA"]` |
| Find City by City Id | ✅ | City | `findCityById(10)` -> `["Los Angeles", "California"]` |
| Find All Cities | ✅ | City | `findAllCities()` -> `[All cities in database]` |
| Find Cities by City name | ✅ | City | `findAllCitiesByCityName("San Francisco")` -> `["San Francisco", "California"]` |
| Find Closest City by latitude/longitude | ✅ | City | `findClosestCityByLatLong(30.438, -84.280)` -> `["Tallahassee", "Florida"]` |
| Find Closest City by BigDecimal lat/long | ✅ | City | `findClosestCityByLatLong(new BigDecimal("30.438"), new BigDecimal("-84.280"))` |
| Find Closest City by String lat/long | ✅ | City | `findClosestCityByLatLong("30.438", "-84.280")` -> `["Tallahassee", "Florida"]` |
| Find Street or Address | ❌ | N/A | Not supported - location4j does not provide street-level details |
| Find Zipcode/Postcode | ❌ | N/A | Not supported - location4j does not include postal code data |
| Find Small Towns/Villages | ❌ | N/A | Not supported - location4j focuses on major cities and administrative divisions |
ℹ️ location4j can parse free text strings with or without punctuation or capitalisation e.g.
> San Francisco, CA, USA
>
> ca united states san francisco
>
> US, San Francisco, california
## More Examples 🧪
**Lookup countries**
For simple lookups the `LocationService` can act like a repository, allow the retrieval of
countries, states and city information.
```java
import com.tomaytotomato.location4j.LocationService;
public class LocationServiceExample {
public static void main(String[] args) {
LocationService locationService = LocationService.builder().build();
// Get all countries
List countries = locationService.findAllCountries();
// Filter European countries
List europeanCountries = countries.stream()
.filter(country -> "Europe".equals(country.getRegion()))
.toList();
// Find Afghanistan by ID
Country afghanistan = locationService.findCountryById(1);
// Find all cities named San Francisco
List cities = locationService.findAllCities("San Francisco");
}
}
```
**Search locations**
Search any text for a location, the `SearchLocationService` can handle formatted or unformatted
text. It will try and find matches against a variety of keywords it has in its dataset.
```java
import com.tomaytotomato.location4j.SearchLocationService;
public class SearchLocationServiceExample {
public static void main(String[] args) {
SearchLocationService searchLocationService = SearchLocationService.builder()
.withTextNormaliser(new DefaultTextNormaliser())
.build();
// Search for Santa Clara
List results = searchLocationService.search("Santa Clara");
// Search for Santa Clara in the USA
List resultsUnitedStates = searchLocationService.search("Santa Clara USA");
// Search for Santa Clara in California (it works with ISO2 or ISO3) codes
List resultsCalifornia = searchLocationService.search("Santa Clara US CA");
}
}
```
## Motivation 🌱
Parsing location data efficiently is crucial for many applications, yet it can be complex and
time-consuming.
Third-party services like Google Location API can be costly, and using large language models can
introduce significant latency.
location4j offers a practical solution with its own dataset, enabling fast and cost-effective
geographical lookups to a city/town level (which is sufficient in most cases).
This allows applications to be built without another external dependency and the overheads that come
with it.
I may add other functionality in the future if needed e.g. geolocation to nearest place, geofencing
etc.
## More Info
[Testing](TESTING.md)
## Credits 🙏
Country data sourced
from [dr5shn/countries-states-cities-database](https://github.com/dr5hn/countries-states-cities-database) [](https://opendatacommons.org/licenses/odbl/)
## License 📜
[MIT License](https://choosealicense.com/licenses/mit/)