repository·master·Indexed 21 days ago
https://github.com/fcambus/telizeA high-performance REST API written in Go that provides IP geolocation data. It utilizes MaxMind DB Reader to cache GeoLite2 City and GeoLite2 ASN databases in RAM for fast responses. The API provides endpoints to retrieve visitor IP addresses in plain text, JSON, or JSONP formats, as well as detailed geolocation and ASN information for specific IP addresses.
To run Telize as a daemon that starts at boot time, follow these steps:
/usr/local/sbin.systemd/telize.service file (provided in the repository) to /etc/systemd/system.systemctl.# After copying files to their respective locations:
systemctl enable telizeBuild and install Telize using the Go tool. All dependencies (including chi and maxminddb-golang) will be automatically fetched and compiled.
go build
go install telizeTelize requires MaxMind's free GeoLite2 databases.
By default, Telize looks for the GeoLite2 City and GeoLite2 ASN databases in the following directory:
/var/db/GeoIP
Retrieve geolocation data for either the visitor or a specific IP address.
Returns location data for the IP address making the request.
http://<host>:<port>/locationhttp://<host>:<port>/location?callback=<callback_name>Returns location data for a provided IP address by appending it to the path.
http://<host>:<port>/location/<IP_ADDRESS>http://<host>:<port>/location/<IP_ADDRESS>?callback=<callback_name># Get location for a specific IP
GET http://127.0.0.1:8080/location/46.19.37.108
# Get location for a specific IP with JSONP
GET http://127.0.0.1:8080/location/46.19.37.108?callback=getlocationYou can retrieve the visitor's IP address in either plain text or JSON/JSONP formats.
Returns the IP address as a simple string.
http://<host>:<port>/ipReturns the IP address in a JSON object.
http://<host>:<port>/jsonipReturns the IP address using a JSONP callback.
http://<host>:<port>/jsonip?callback=<callback_name># JSON example
GET http://127.0.0.1:8080/jsonip
# JSONP example
GET http://127.0.0.1:8080/jsonip?callback=getipTelize requires MaxMind GeoIP2 databases to function. By default, the application expects the following database files to be present at these specific paths:
/var/db/GeoIP/GeoLite2-ASN.mmdb/var/db/GeoIP/GeoLite2-City.mmdbIf these files are missing or inaccessible, the application will log a fatal error and exit during startup.
When an invalid IP address is provided, Telize returns an HTTP 400 Bad Request error with a JSON-encoded message.
401: Input string is not a valid IP addressTelize automatically handles the X-Forwarded-For HTTP header. If present, it will return data for the first IP address in the list.
CORS is enabled by default with the policy:
Access-Control-Allow-Origin: *
When running the Telize binary, you can specify the server host and port using command-line flags. By default, Telize binds to 127.0.0.1:8080.
# Example usage with flags
./telize -host "0.0.0.0" -port "9000"The /ip endpoint returns the requester's IP address as a plain text string. The response includes a Cache-Control: no-cache header to ensure the IP is not cached by intermediate proxies.
GET /ip
Response Body:
127.0.0.1The /location/{ip} endpoint provides detailed geolocation and ASN (Autonomous System Number) information for a given IP address. If the {ip} URL parameter is omitted, the service defaults to the requester's IP address.
Error Handling:
If the provided IP address is invalid or if the lookup fails, the API returns a 400 or 401 error with the message: "Input string is not a valid IP address".
GET /location/{ip}
Example Response:
{
"IP": "127.0.0.1",
"Continent": "EU",
"Country": "United Kingdom",
"CountryCode": "GB",
"CountryCode3": "GBR",
"IsInEuropeanUnion": false,
"City": "London",
"PostalCode": "EC1A 1BB",
"Latitude": 51.5074,
"Longitude": -0.1278,
"TimeZone": "Europe/London",
"ASN": 12345,
"Organization": "Example ISP",
"Region": "Greater London",
"RegionCode": "GL",
"Offset": -0
}The /jsonip endpoint returns the requester's IP address wrapped in a JSON object. This is useful for programmatic access where a structured format is required.
GET /jsonip
Response Body:
{
"IP": "127.0.0.1"
}Telize provides several HTTP endpoints to retrieve IP address information and geolocation data. Most endpoints support both GET and HEAD requests.
/ip: Returns the client's IP address in plain text./jsonip: Returns the client's IP address in JSON format.These endpoints return location data based on the client's IP or a specific IP provided in the path.
/geoip: Returns location data for the client's IP./geoip/{ip}: Returns location data for the specified IP./location: Returns location data for the client's IP./location/{ip}: Returns location data for the specified IP.Note: /geoip/ and /location/ (with trailing slashes) are aliases for the base geolocation endpoints.
# Get plain text IP
curl http://localhost:8080/ip
# Get IP in JSON format
curl http://localhost:8080/jsonip
# Get geolocation for a specific IP
curl http://localhost:8080/geoip/8.8.8.8