{"id":22685374,"url":"https://github.com/tomaytotomato/location4j","last_synced_at":"2025-04-12T19:36:15.698Z","repository":{"id":249857282,"uuid":"829971910","full_name":"tomaytotomato/location4j","owner":"tomaytotomato","description":"A Java library for efficient geographical lookups without external APIs. 🌎 Provides country, state, and city identification from free text with a built-in dataset. ","archived":false,"fork":false,"pushed_at":"2025-03-21T18:30:31.000Z","size":11210,"stargazers_count":52,"open_issues_count":5,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T13:53:53.792Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"https://javadoc.io/doc/com.tomaytotomato/location4j","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tomaytotomato.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"tomaytotomato"}},"created_at":"2024-07-17T11:02:50.000Z","updated_at":"2025-03-24T06:00:31.000Z","dependencies_parsed_at":"2025-03-16T22:26:35.825Z","dependency_job_id":"02eb6211-417a-45ab-981d-c77c046feee7","html_url":"https://github.com/tomaytotomato/location4j","commit_stats":null,"previous_names":["tomaytotomato/location4j"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomaytotomato%2Flocation4j","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomaytotomato%2Flocation4j/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomaytotomato%2Flocation4j/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomaytotomato%2Flocation4j/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomaytotomato","download_url":"https://codeload.github.com/tomaytotomato/location4j/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248623313,"owners_count":21135226,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2024-12-09T22:14:36.876Z","updated_at":"2025-04-12T19:36:15.686Z","avatar_url":"https://github.com/tomaytotomato.png","language":"Java","funding_links":["https://github.com/sponsors/tomaytotomato"],"categories":[],"sub_categories":[],"readme":"# location4j 🌎4️⃣♨️\n\n![Build Status](https://github.com/tomaytotomato/location4j/actions/workflows/build.yml/badge.svg)\n[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=tomaytotomato_location4j\u0026metric=bugs)](https://sonarcloud.io/summary/new_code?id=tomaytotomato_location4j)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=tomaytotomato_location4j\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=tomaytotomato_location4j)\n[![javadoc](https://javadoc.io/badge2/com.tomaytotomato/location4j/1.0.6/javadoc.svg)](https://javadoc.io/doc/com.tomaytotomato/location4j/1.0.6)\n![GitHub commit activity](https://img.shields.io/github/commit-activity/m/tomaytotomato/location4j)\n![GitHub License](https://img.shields.io/github/license/tomaytotomato/location4j)\n[![libs.tech recommends](https://libs.tech/project/829971910/badge.svg)](https://libs.tech/project/829971910/location4j)\n\nlocation4j is a simple Java library designed for efficient and accurate geographical data lookups\nfor countries, states, and cities. πŸ—ΊοΈ\n\nUnlike other libraries, it operates without relying on third-party APIs, making it both\ncost-effective and fast. 🏎️\n\nIts built-in dataset provides quick lookups and no need for external HTTP calls. πŸ“€\n\n## Requirements πŸ“‹\n\n- Java 21 or higher (uses JPMS and Java 21 features)\n- Maven 3.8+ (for building from source)\n\n## Setup πŸš€\n\nGet the latest version of the location4j library by adding it to your Maven pom.xml\n\n```xml\n\n\u003cdependency\u003e\n \u003cgroupId\u003ecom.tomaytotomato\u003c/groupId\u003e\n \u003cartifactId\u003elocation4j\u003c/artifactId\u003e\n \u003cversion\u003e1.0.6\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n**Gradle**\n\n```gradle\nimplementation group: 'com.tomaytotomato', name: 'location4j', version: '1.0.6'\n```\n\n## Quick Example πŸ—\n\n```java\nimport com.tomaytotomato.location4j.SearchLocationService;\n\npublic class Main {\n\n public static void main(String[] args) {\n SearchLocationService searchLocationService = SearchLocationService.builder().build();\n\n // Find all locations named San Francisco\n List\u003cLocation\u003e results = searchLocationService.search(\"san francisco\");\n printResults(results);\n\n // Narrow search to the US\n results = searchLocationService.search(\"san francisco, us\");\n printResults(results);\n\n // Narrow search further to California\n results = searchLocationService.search(\"san francisco, us california\");\n printResults(results);\n }\n\n private static void printResults(List\u003cLocation\u003e results) {\n System.out.println(\"Locations found: \" + results.size());\n results.forEach(location -\u003e {\n System.out.println(\"Country: \" + location.getCountryName());\n System.out.println(\"State: \" + location.getStateName());\n System.out.println(\"City: \" + location.getCityName());\n });\n }\n}\n\n```\n\n## Features πŸ”¬\n\n| Feature | Supported | Object | Example |\n|--------------------------------------------|-----------|----------|---------------------------------------------------------------------------------|\n| Search (free text) | βœ… | Location | `search(\"kyiv\")` -\u003e `\"Kyiv, Ukraine, Europe, UA\"` |\n| Find All Countries | βœ… | Country | `findAllCountries()` -\u003e `[\"Belgium\", \"Canada\", ...]` |\n| Find Country by Id | βœ… | Country | `findCountryById(1)` -\u003e `[\"Afghanistan\"]` |\n| Find Country by ISO2 code | βœ… | Country | `findCountryByISO2Code(\"CA\")` -\u003e `[\"Canada\"]` |\n| Find Country by ISO3 code | βœ… | Country | `findCountryByISO3Code(\"CAN\")` -\u003e `[\"Canada\"]` |\n| Find Country by Name | βœ… | Country | `findCountryByName(\"Canada\")` -\u003e `[\"Canada\"]` |\n| Find Country by Localised name | βœ… | Country | `findCountryByLocalisedName(\"Belgique\")` -\u003e `[\"Belgium\"]` |\n| Find Countries by State name | βœ… | Country | `findAllCountriesByStateName(\"Texas\")` -\u003e `[\"USA\"]` |\n| Find States by State name | βœ… | State | `findAllStatesByStateName(\"Texas\")` -\u003e `[\"Texas\", \"USA\"]` |\n| Find State by State Id | βœ… | State | `findStateById(5)` -\u003e `[\"California\", \"USA\"]` |\n| Find States by State code | βœ… | State | `findAllStatesByStateCode(\"CA\")` -\u003e `[\"California\", \"USA\"]` |\n| Find City by City Id | βœ… | City | `findCityById(10)` -\u003e `[\"Los Angeles\", \"California\"]` |\n| Find All Cities | βœ… | City | `findAllCities()` -\u003e `[All cities in database]` |\n| Find Cities by City name | βœ… | City | `findAllCitiesByCityName(\"San Francisco\")` -\u003e `[\"San Francisco\", \"California\"]` |\n| Find Closest City by latitude/longitude | βœ… | City | `findClosestCityByLatLong(30.438, -84.280)` -\u003e `[\"Tallahassee\", \"Florida\"]` |\n| Find Closest City by BigDecimal lat/long | βœ… | City | `findClosestCityByLatLong(new BigDecimal(\"30.438\"), new BigDecimal(\"-84.280\"))` |\n| Find Closest City by String lat/long | βœ… | City | `findClosestCityByLatLong(\"30.438\", \"-84.280\")` -\u003e `[\"Tallahassee\", \"Florida\"]` |\n| Find Street or Address | ❌ | N/A | Not supported - location4j does not provide street-level details |\n| Find Zipcode/Postcode | ❌ | N/A | Not supported - location4j does not include postal code data |\n| Find Small Towns/Villages | ❌ | N/A | Not supported - location4j focuses on major cities and administrative divisions |\n\nℹ️ location4j can parse free text strings with or without punctuation or capitalisation e.g.\n\u003e San Francisco, CA, USA\n\u003e\n\u003e ca united states san francisco\n\u003e\n\u003e US, San Francisco, california\n\n## More Examples πŸ§ͺ\n\n**Lookup countries**\n\nFor simple lookups the `LocationService` can act like a repository, allow the retrieval of\ncountries, states and city information.\n\n```java\n\nimport com.tomaytotomato.location4j.LocationService;\n\npublic class LocationServiceExample {\n\n public static void main(String[] args) {\n LocationService locationService = LocationService.builder().build();\n\n // Get all countries\n List\u003cCountry\u003e countries = locationService.findAllCountries();\n\n // Filter European countries\n List\u003cCountry\u003e europeanCountries = countries.stream()\n .filter(country -\u003e \"Europe\".equals(country.getRegion()))\n .toList();\n\n // Find Afghanistan by ID\n Country afghanistan = locationService.findCountryById(1);\n\n // Find all cities named San Francisco\n List\u003cCity\u003e cities = locationService.findAllCities(\"San Francisco\");\n\n }\n}\n\n```\n\n**Search locations**\n\nSearch any text for a location, the `SearchLocationService` can handle formatted or unformatted\ntext. It will try and find matches against a variety of keywords it has in its dataset.\n\n```java\n\nimport com.tomaytotomato.location4j.SearchLocationService;\n\npublic class SearchLocationServiceExample {\n\n public static void main(String[] args) {\n SearchLocationService searchLocationService = SearchLocationService.builder()\n .withTextNormaliser(new DefaultTextNormaliser())\n .build();\n\n // Search for Santa Clara\n List\u003cLocation\u003e results = searchLocationService.search(\"Santa Clara\");\n\n // Search for Santa Clara in the USA\n List\u003cLocation\u003e resultsUnitedStates = searchLocationService.search(\"Santa Clara USA\");\n\n // Search for Santa Clara in California (it works with ISO2 or ISO3) codes\n List\u003cLocation\u003e resultsCalifornia = searchLocationService.search(\"Santa Clara US CA\");\n }\n}\n\n```\n\n## Motivation 🌱\n\nParsing location data efficiently is crucial for many applications, yet it can be complex and\ntime-consuming.\n\nThird-party services like Google Location API can be costly, and using large language models can\nintroduce significant latency.\n\nlocation4j offers a practical solution with its own dataset, enabling fast and cost-effective\ngeographical lookups to a city/town level (which is sufficient in most cases).\n\nThis allows applications to be built without another external dependency and the overheads that come\nwith it.\n\nI may add other functionality in the future if needed e.g. geolocation to nearest place, geofencing\netc.\n\n## More Info\n\n[Testing](TESTING.md)\n\n## Credits πŸ™\n\nCountry data sourced\nfrom [dr5shn/countries-states-cities-database](https://github.com/dr5hn/countries-states-cities-database) [![License: ODbL](https://img.shields.io/badge/License-ODbL-brightgreen.svg)](https://opendatacommons.org/licenses/odbl/)\n\n## License πŸ“œ\n\n[MIT License](https://choosealicense.com/licenses/mit/)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomaytotomato%2Flocation4j","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomaytotomato%2Flocation4j","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomaytotomato%2Flocation4j/lists"}