telize

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

README.md (3670B)


      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 ## Usage
     80 
     81 For complete API documentation and usage examples, please check the
     82 project site.
     83 
     84 ### Get IP address in Plain text format
     85 
     86 - Example: http://127.0.0.1/ip
     87 
     88 ### Get IP address in JSON format
     89 
     90 - Example (JSON): http://127.0.0.1/jsonip
     91 - Example (JSONP): http://127.0.0.1/jsonip?callback=getip
     92 
     93 ### Get IP address location in JSON format
     94 
     95 Calling the API endpoint without any parameter will return the visitor
     96 IP address:
     97 
     98 - Example (JSON): http://127.0.0.1/location
     99 - Example (JSONP): http://127.0.0.1/location?callback=getgeoip
    100 
    101 Appending an IP address as parameter will return location information for
    102 the given address:
    103 
    104 - Example (JSON): http://127.0.0.1/location/46.19.37.108
    105 - Example (JSONP): http://127.0.0.1/location/46.19.37.108?callback=getgeoip
    106 
    107 ## License
    108 
    109 Telize is released under the BSD 2-Clause license. See `LICENSE` file
    110 for details.
    111 
    112 ## Author
    113 
    114 Telize is developed by Frederic Cambus.
    115 
    116 - Site: https://www.cambus.net
    117 
    118 ## Resources
    119 
    120 Project homepage: https://www.telize.com
    121 
    122 Latest tarball release: https://www.statdns.com/telize/telize-3.0.0.tar.gz
    123 
    124 GitHub: https://github.com/fcambus/telize
    125 
    126 [1]: https://kore.io
    127 [2]: https://github.com/maxmind/libmaxminddb
    128 [3]: https://dev.maxmind.com/geoip/geoip2/geolite2/
    129 [4]: https://www.logswan.org