telize

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

commit 5f2fad979192d4702dca11d4534d9093edda8574
Author: Frederic Cambus <fcambus@users.sourceforge.net>
Date:   Wed, 21 Aug 2013 13:30:51 +0200

Initial Telize release

Diffstat:
AAUTHORS | 6++++++
AChangeLog | 3+++
ALICENSE | 28++++++++++++++++++++++++++++
AREADME.md | 107+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Atelize | 87+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
5 files changed, 231 insertions(+), 0 deletions(-)

diff --git a/AUTHORS b/AUTHORS @@ -0,0 +1,6 @@ +Telize is developed by : + +Frederic Cambus <fcambus AT users DOT sourceforge DOT net> + +Site : http://www.cambus.net +Twitter : @fcambus diff --git a/ChangeLog b/ChangeLog @@ -0,0 +1,3 @@ +Telize 1.00 (2013-08-21) + +- Initial release diff --git a/LICENSE b/LICENSE @@ -0,0 +1,28 @@ +Copyright (c) 2013, Frederic Cambus +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + + * Neither the name of Telize nor the names of its contributors may be + used to endorse or promote products derived from this software + without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE +LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md @@ -0,0 +1,107 @@ + + t e l i z e + _______________________ + ______\ /_______ + \\ \\ ___ // / + __ \ ____ \ __ / \ _____/\ / ____ + ___/ \____/ _//____/ \___\___/___\__ /__/ _//____ + \\__ ____ __/ __ __ ____ ____ __/ __/// + / \_ |/ \_ / \/ /_/ |/ \_ + \\\ ___/\___ /____/\_______/\ ___/\___ / + <0(--- \__/ -h7- \______/ \ . \__/ ---- \______/ --(0> + \ .\ /. . + \ .\ // / + \______\\ //______/ + Y + +## Description + +Telize is a REST API built on Nginx and Lua allowing to get a visitor IP +address and to query location information from any IP address. It outputs +JSON-encoded IP geolocation data, and supports both JSON and JSONP. + +## Requirements + +### Nginx modules + +Telize requires Nginx compiled with the following modules : + +- GeoIP (Optional HTTP modules : --with-http_geoip_module) +- HttpRealipModule (Optional HTTP module : --with-http_realip_module) +- HttpEchoModule (Third party module (ngx_echo) : http://wiki.nginx.org/HttpEchoModule) +- HttpLuaModule (Third party module (ngx_lua) : http://wiki.nginx.org/HttpLuaModule) + +If you are using Debian stable, the `nginx-extras` package have these +modules compiled-in. + +### Lua modules + +Telize requires the following Lua module : + +- Lua CJSON + +Installing Via LuaRocks : + + luarocks install lua-cjson + +## Installation + +Edit `nginx.conf` to add directives specifying the path to the GeoIP database +files, within the http block : + + http { + + ... + + geoip_country /usr/share/GeoIP/GeoIP.dat; + geoip_city /usr/share/GeoIP/GeoLiteCity.dat; + } + +Then deploy the API configuration file `telize` to the appropriate location on +your system, and reload Nginx configuration. + +## Usage + +For complete API documentation and JavaScript API usage examples, please check +the project site : http://www.telize.com + +### Get IP address in Plain text format : + +- Example : http://www.telize.com/ip + +### Get IP address in JSON format : + +- Example (JSON) : http://www.telize.com/jsonip +- Example (JSONP) : http://www.telize.com/jsonip?callback=getip + +### Get IP address location in JSON format : + +Calling the API endpoint without any parameter will return the visitor +IP address : + +- Example (JSON) : http://www.telize.com/geoip +- Example (JSONP) : http://www.telize.com/geoip?callback=getgeoip + +Appending an IP address as parameter will return location information for +this IP address : + +- Example (JSON) : http://www.telize.com/geoip/46.19.37.108 +- Example (JSONP) : http://www.telize.com/geoip/46.19.37.108?callback=getgeoip + +## License + +Telize is released under the BSD 3-Clause license. See `LICENSE` file +for details. + +## Author + +Telize is developed by Frederic Cambus + +- Site : http://www.cambus.net +- Twitter: http://twitter.com/fcambus + +## Resources + +Project Homepage : http://www.telize.com + +GitHub : https://github.com/fcambus/telize diff --git a/telize b/telize @@ -0,0 +1,87 @@ +############################################################################### +# # +# Telize 1.00 (c) by Frederic Cambus 2013 # +# http://www.telize.com # +# # +# Created: 2013/08/15 # +# Last Updated: 2013/08/21 # +# # +# Telize is released under the BSD 3-Clause license. # +# See LICENSE file for details. # +# # +############################################################################### + +server { + server_name 127.0.0.1; + + keepalive_timeout 0; + gzip off; + + location /ip + { + charset off; + default_type text/plain; + + echo $remote_addr; + } + + location /jsonip + { + echo_exec /jsonify ip=$remote_addr&callback=$arg_callback; + } + + rewrite ^/geoip$ /geoip/ last; + + location ~ /geoip/(?<ip>.*) { + if ($ip = "") + { + set $ip $remote_addr; + } + + proxy_set_header X-Real-IP $ip; + proxy_pass $scheme://127.0.0.1/localize?callback=$arg_callback; + } + + location /localize { + set_real_ip_from 127.0.0.1; + + echo_exec /jsonify ip=$remote_addr&country_code=$geoip_city_country_code&country_code3=$geoip_city_country_code3&country=$geoip_city_country_name&region_code=$geoip_region&region=$geoip_region_name&city=$geoip_city&postal_code=$geoip_postal_code&continent_code=$geoip_city_continent_code&latitude=$geoip_latitude&longitude=$geoip_longitude&dma_code=$geoip_dma_code&area_code=$geoip_area_code&callback=$arg_callback; + } + + location /jsonify { + charset iso-8859-1; + default_type application/json; + + content_by_lua ' + local cjson = require("cjson") + + local ip = ngx.var.arg_ip + local country_code = ngx.var.arg_country_code ~= "" and ngx.var.arg_country_code or nil + local country_code3 = ngx.var.arg_country_code3 ~= "" and ngx.var.arg_country_code3 or nil + local country = ngx.var.arg_country ~= "" and ngx.var.arg_country or nil + local region = ngx.var.arg_region ~= "" and ngx.var.arg_region or nil + local region_code = ngx.var.arg_region_code ~= "" and ngx.var.arg_region_code or nil + local city = ngx.var.arg_city ~= "" and ngx.var.arg_city or nil + local postal_code = ngx.var.arg_postal_code ~= "" and ngx.var.arg_postal_code or nil + local continent_code = ngx.var.arg_continent_code ~= "" and ngx.var.arg_continent_code or nil + local latitude = ngx.var.arg_latitude ~= "" and tonumber(ngx.var.arg_latitude) or nil + local longitude = ngx.var.arg_longitude ~= "" and tonumber(ngx.var.arg_longitude) or nil + local dma_code = ngx.var.arg_dma_code ~= "" and ngx.var.arg_dma_code or nil + local area_code = ngx.var.arg_area_code ~= "" and ngx.var.arg_area_code or nil + local callback = ngx.var.arg_callback + + if ip == "127.0.0.1" then + ngx.status = ngx.HTTP_BAD_REQUEST + ngx.say(cjson.encode({code = 401, message = "Input string is not a valid IP address"})) + ngx.exit(ngx.HTTP_OK) + end + + json = cjson.encode({ip = ip, country_code = country_code, country_code3 = country_code3, country = country, region_code = region_code, region = region, city = city, postal_code = postal_code, continent_code = continent_code, latitude = latitude, longitude = longitude, dma_code = dma_code, area_code = area_code}) + + if callback ~= "" then + ngx.say(callback, "(", json, ");") + else + ngx.say(json) + end'; + } +}