telize

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

README.md (3957B)


      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 C with Kore allowing to get a visitor IP
     20 address and to query location information from any IP address. It outputs
     21 JSON-encoded IP geolocation data, and supports both JSON and JSONP.
     22 
     23 Geolocation operations are performed using libmaxminddb which caches the
     24 database in RAM. Therefore, Telize has very minimal overhead and should
     25 be blazing fast.
     26 
     27 ## Requirements
     28 
     29 ### Dependencies
     30 
     31 Telize requires [Kore][1] 4.0.0+ and [libmaxminddb][2].
     32 
     33 ### GeoIP2 databases
     34 
     35 Telize requires the free [GeoLite2 databases][3] from MaxMind.
     36 
     37 The path to the `GeoLite2 City` and `GeoLite2 ASN` databases can be configured
     38 in `conf/build.conf` via the `GEOIP2DIR` macro, pointing to `/var/db/GeoIP`
     39 by default.
     40 
     41 ## Building
     42 
     43 Using the kodev tool:
     44 
     45 	kodev build
     46 
     47 ## Configuration
     48 
     49 By default, Telize will only listen on `127.0.0.1` and `::1`. To add more
     50 listeners, `bind` directives should be added in `conf/telize.conf` in the
     51 server blocks.
     52 
     53 ## Running
     54 
     55 Using the kodev tool:
     56 
     57 	kodev run
     58 
     59 ## Access logs
     60 
     61 The default Telize configuration does not have logging enabled, it must be
     62 configured manually. There are commented out `accesslog` directives in
     63 `conf/telize.conf` for each domain block.
     64 
     65 If your Telize instance produces lots of logs, [Logswan][4] might be of
     66 interest.
     67 
     68 ## Telize and proxies
     69 
     70 Telize handles the 'X-Forwarded-For' HTTP header if present, and returns
     71 data for the first IP address of the list.
     72 
     73 ## CORS Support (Cross-origin resource sharing)
     74 
     75 Telize has CORS enabled by default with the following policy:
     76 
     77 	Access-Control-Allow-Origin: *
     78 
     79 ## Timezone offsets
     80 
     81 Since version 3.0.0, Telize now dynamically calculates timezone offsets
     82 (UTC time offset) and adds data to the payload.
     83 
     84 On Alpine Linux, the 'tzdata' package needs to be installed, otherwise
     85 localtime() will not return any data.
     86 
     87 ## Usage
     88 
     89 For complete API documentation and usage examples, please check the
     90 project site.
     91 
     92 ### Get IP address in Plain text format
     93 
     94 - Example: http://127.0.0.1:8080/ip
     95 
     96 ### Get IP address in JSON format
     97 
     98 - Example (JSON): http://127.0.0.1:8080/jsonip
     99 - Example (JSONP): http://127.0.0.1:8080/jsonip?callback=getip
    100 
    101 ### Get IP address location in JSON format
    102 
    103 Calling the API endpoint without any parameter will return the visitor
    104 IP address:
    105 
    106 - Example (JSON): http://127.0.0.1:8080/location
    107 - Example (JSONP): http://127.0.0.1:8080/location?callback=getgeoip
    108 
    109 Appending an IP address as parameter will return location information for
    110 the given address:
    111 
    112 - Example (JSON): http://127.0.0.1:8080/location/46.19.37.108
    113 - Example (JSONP): http://127.0.0.1:8080/location/46.19.37.108?callback=getgeoip
    114 
    115 ## License
    116 
    117 Telize is released under the BSD 2-Clause license. See `LICENSE` file
    118 for details.
    119 
    120 ## Author
    121 
    122 Telize is developed by Frederic Cambus.
    123 
    124 - Site: https://www.cambus.net
    125 
    126 ## Resources
    127 
    128 Project homepage: https://www.telize.com
    129 
    130 Latest tarball release: https://www.statdns.com/telize/telize-3.0.0.tar.gz
    131 
    132 GitHub: https://github.com/fcambus/telize
    133 
    134 [1]: https://kore.io
    135 [2]: https://github.com/maxmind/libmaxminddb
    136 [3]: https://dev.maxmind.com/geoip/geoip2/geolite2/
    137 [4]: https://www.logswan.org