telize

High performance JSON IP and GeoIP REST API (IP Geolocation)
Log | Files | Refs | README | LICENSE

README.md (4206B)

      1 
      2                                t  e  l  i  z  e
      3                            _______________________
      4                      ______\                     /_______
      5                     \\     \\           ___     //      /
      6                __    \ ____  \   __    /   \   _____/\ / ____
      7            ___/  \____/  _//____/  \___\___/___\__   /__/  _//____
      8           \\__    ____  __/  __     __      ____    ____  __/  __///
      9             /      \_   |/    \_     /       \/     /_/   |/    \_
     10           \\\   ___/\___       /____/\_______/\   ___/\___       /
     11       <0(--- \__/ -h7- \______/   \       .    \__/ ---- \______/ --(0>
     12                            \      .\     /.      .
     13                             \      .\   //      /
     14                              \______\\ //______/
     15                                       Y
     16 
     17 ## Description
     18 
     19 Telize is a REST API built in Go allowing to get a visitor IP address and
     20 to query location information from any IP address. It outputs JSON-encoded
     21 IP geolocation data, and supports both JSON and JSONP.
     22 
     23 Geolocation operations are performed using the MaxMind DB Reader for Go
     24 which caches the database in RAM. Therefore, Telize has very minimal
     25 overhead and should be blazing fast.
     26 
     27 ## Requirements
     28 
     29 Telize requires the following Go libraries:
     30 
     31 - chi: lightweight, idiomatic and composable router - https://github.com/go-chi/chi
     32 - maxminddb-golang: MaxMind DB Reader for Go - https://github.com/oschwald/maxminddb-golang
     33 
     34 ### GeoIP2 databases
     35 
     36 Telize requires the free [GeoLite2 databases][1] from MaxMind.
     37 
     38 Telize will look for the `GeoLite2 City` and `GeoLite2 ASN` databases in
     39 `/var/db/GeoIP` by default.
     40 
     41 ## Installation
     42 
     43 Build and install with the `go` tool, all dependencies will be automatically
     44 fetched and compiled:
     45 
     46 	go build
     47 	go install telize
     48 
     49 ## Usage
     50 
     51 By default, Telize will bind on localhost, port 8080.
     52 
     53 	USAGE:
     54 	  -host string
     55 	    	Set the server host (default "127.0.0.1")
     56 	  -port string
     57 	    	Set the server port (default "8080")
     58 	  -version
     59 	    	Display version
     60 
     61 ## Running Telize at boot time
     62 
     63 ### Systemd unit file
     64 
     65 Telize is bundled with a systemd unit file, see: `systemd/telize.service`
     66 
     67 Copy the `systemd/telize.service` file in `/etc/systemd/system` and the Telize
     68 binary in `/usr/local/sbin`.
     69 
     70 To launch the daemon at startup, run:
     71 
     72 	systemctl enable telize
     73 
     74 ## Making Queries
     75 
     76 For complete API documentation and usage examples, please check the
     77 project site.
     78 
     79 Telize supports JSONP callbacks.
     80 
     81 ### Get IP address in Plain text format
     82 
     83 - Example: http://127.0.0.1:8080/ip
     84 
     85 ### Get IP address in JSON format
     86 
     87 - Example (JSON): http://127.0.0.1:8080/jsonip
     88 - Example (JSONP): http://127.0.0.1:8080/jsonip?callback=getip
     89 
     90 ### Get IP address location in JSON format
     91 
     92 Calling the API endpoint without any parameter will return the visitor
     93 IP address:
     94 
     95 - Example (JSON): http://127.0.0.1:8080/location
     96 - Example (JSONP): http://127.0.0.1:8080/location?callback=getlocation
     97 
     98 Appending an IP address as parameter will return location information for
     99 the given address:
    100 
    101 - Example (JSON): http://127.0.0.1:8080/location/46.19.37.108
    102 - Example (JSONP): http://127.0.0.1:8080/location/46.19.37.108?callback=getlocation
    103 
    104 ## Client Errors
    105 
    106 When incorrect user input is entered, the server returns an HTTP 400 Error
    107 (Bad Request), along with a JSON-encoded error message.
    108 
    109 - Code 401: Input string is not a valid IP address
    110 
    111 ## Telize and proxies
    112 
    113 Telize handles the 'X-Forwarded-For' HTTP header if present, and returns
    114 data for the first IP address of the list.
    115 
    116 ## CORS Support (Cross-origin resource sharing)
    117 
    118 Telize has CORS enabled by default with the following policy:
    119 
    120 	Access-Control-Allow-Origin: *
    121 
    122 ## Timezone offsets
    123 
    124 Since version 3.0.0, Telize now dynamically calculates timezone offsets
    125 (UTC time offset) and adds data to the payload.
    126 
    127 ## License
    128 
    129 Telize is released under the BSD 2-Clause license. See `LICENSE` file
    130 for details.
    131 
    132 ## Author
    133 
    134 Telize is developed by Frederic Cambus.
    135 
    136 - Site: https://www.cambus.net
    137 
    138 ## Resources
    139 
    140 Project homepage: https://www.telize.com
    141 
    142 Latest tarball release: https://www.statdns.com/telize/telize-3.1.1.tar.gz
    143 
    144 GitHub: https://github.com/fcambus/telize
    145 
    146 [1]: https://dev.maxmind.com/geoip/geoip2/geolite2/