https://github.com/matheushoske/hoskes.geoapi
A completely free, open, self-hosted alternative to things like IPAPI or GeoPlugin – but with the ability to add plugins and customize the API response. Something that could evolve into a community-driven, plugin-based API playground.
https://github.com/matheushoske/hoskes.geoapi
api geolocation iplocation javascript nodejs
Last synced: about 2 months ago
JSON representation
A completely free, open, self-hosted alternative to things like IPAPI or GeoPlugin – but with the ability to add plugins and customize the API response. Something that could evolve into a community-driven, plugin-based API playground.
- Host: GitHub
- URL: https://github.com/matheushoske/hoskes.geoapi
- Owner: matheushoske
- License: mit
- Created: 2025-04-07T03:39:45.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-22T21:17:05.000Z (about 1 year ago)
- Last Synced: 2025-04-22T22:28:01.952Z (about 1 year ago)
- Topics: api, geolocation, iplocation, javascript, nodejs
- Language: JavaScript
- Homepage: https://geoapi-hoskes.onrender.com/json.gp
- Size: 27.9 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 📍 Hoskes LocPlugin API
**A **free**, **lightweight**, **open source**, GeoPlugin-style IP geolocation API built with 💙 for the community.**
🟣 **Live URL:** [https://geoapi-hoskes.onrender.com/json.gp](https://geoapi-hoskes.onrender.com/json.gp)
📦 **License:** MIT
🤝 **Open for contributions and issues**
---
## 🚀 How It Works
This API detects the **network IP** of the requester and returns detailed geographic information, including:
- City
- Region
- Country
- Continent
- Postal Code
- Latitude & Longitude
- Timezone
- ...and more!
---
- 🌍 IP-based location lookup using MaxMind GeoLite2
- ⚡ Fast response time with accurate delay reporting
- 🔌 Plugin support via `?plugins=plugin1,plugin2` in the URL
- 🎯 **NEW**: Query specific IP addresses via `?ip=1.1.1.1` parameter
- ✅ Currently supported plugins:
- `weather`: Current weather based on coordinates
- `language`: Primary language based on country
Access via GET:
```bash
# Get location for your own IP
https://geoapi-hoskes.onrender.com/json.gp
# Get location for a specific IP
https://geoapi-hoskes.onrender.com/json.gp?ip=1.1.1.1
# Get location for specific IP with plugins
https://geoapi-hoskes.onrender.com/json.gp?ip=8.8.8.8&plugins=weather,language
```
---
## ✨ Example Response
```json
{
"hoskes_locplugin_request": "178.238.10.15",
"hoskes_locplugin_status": 200,
"hoskes_locplugin_delay": "0.45ms",
"hoskes_locplugin_credit": "Returned data includes GeoLite2 data created by MaxMind, available from \u003Ca href='https://www.maxmind.com'\u003Ehttps://www.maxmind.com\u003C/a\u003E.",
"hoskes_locplugin_city": "Canary Wharf",
"hoskes_locplugin_region": "England",
"hoskes_locplugin_regionCode": "ENG",
"hoskes_locplugin_regionName": "England",
"hoskes_locplugin_countryCode": "GB",
"hoskes_locplugin_countryName": "United Kingdom",
"hoskes_locplugin_inEUunion": 0,
"hoskes_locplugin_continentCode": "EU",
"hoskes_locplugin_continentName": "Europe",
"hoskes_locplugin_latitude": "51.5064",
"hoskes_locplugin_longitude": "-0.02",
"hoskes_locplugin_locationAccuracyRadius": "20",
"hoskes_locplugin_timezone": "Europe/London",
"hoskes_locplugin_postalCode": "E14"
}
```
## 🔌 Plugins System
Plugins run only if requested via query string:
```bash
/json.gp?plugins=weather,language
```
Each plugin enriches the JSON response. Plugins are modular and stored in `/plugins`.
---
## ✨ Example Response With Plugins
```json
{
"hoskes_locplugin_request": "179.172.163.15",
...
"hoskes_locplugin_weather": "30°C ☀️", //Weather plugin
"hoskes_locplugin_language": "English", //Language plugin
"hoskes_locplugin_langcode": "en" //Language plugin
}
```
---
## 🧠 Built With
- Node.js + Express
- MaxMind GeoLite2 database
- `request-ip` for IP extraction
---
## 🛠️ How to Use (For devs)
1. Clone this repo:
```bash
git clone https://github.com/matheushoske/hoskes.geoapi.git
```
2. Download the [GeoLite2-City.mmdb](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data) and replace it in the project root (optional [For updated data]).
3. Install dependencies:
```bash
npm install
```
```bash
node index.js
```
Access via:
`http://localhost:3000/json.gp?plugins=weather,language`
**Examples:**
- `http://localhost:3000/json.gp` - Get your own IP location
- `http://localhost:3000/json.gp?ip=1.1.1.1` - Get location for specific IP
- `http://localhost:3000/json.gp?ip=8.8.8.8&plugins=weather,language` - Get location with plugins
## 📄 License
This project is licensed under the [MIT License](LICENSE).
---
## 🙏 Credit
- Geo data provided by [MaxMind GeoLite2](https://www.maxmind.com).
## 🤝 Contributing
- Submit issues freely
- Create pull requests at any time
- Add your own plugin in `/plugins` and PR!
Made with ❤️ by [@matheushoske](https://github.com/matheushoske) for the community 💜