Serverless GeoIP API
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
config
events
lib
resources
services
stages
.editorconfig
.eslintrc.js
.gitignore
.npmrc
.nvmrc
Readme.md
package-lock.json
package.json
serverless.yml
webpack.config.js

Readme.md

Serverless GeoIP API

Serverless API to gather Geo Infos about IPs, using Maxmind's databases (City, Country, ASN).

This project provides a cost effective serverless GeoIP service, leveraging several AWS products:

Usage

Combined City and ASN

curl -H "x-api-key: xxxxxx" https://ipinfo.example.com/ipv4/8.8.8.8

Specific database

curl -H "x-api-key: xxxxxx" https://ipinfo.example.com/ipv4/8.8.8.8/city
curl -H "x-api-key: xxxxxx" https://ipinfo.example.com/ipv4/8.8.8.8/country
curl -H "x-api-key: xxxxxx" https://ipinfo.example.com/ipv4/8.8.8.8/asn

Country Name from country code

curl -H "x-api-key: xxxxxx" https://ipinfo.example.com/country/us

Cloudfront Edge info from edge code

curl -H "x-api-key: xxxxxx" https://ipinfo.example.com/edge/NRT52

Caller IP infos

Just the IP as text

curl -H "x-api-key: xxxxxx" https://ipinfo.example.com/ifconfig

IP with ASN, Country and City informations

curl -H "x-api-key: xxxxxx" https://ipinfo.example.com/ifconfig/detail

Install

A working serverless.com, nvm, aws-cli is needed.

git clone https://github.com/Spuul/geoip-serverless
cd geoip-serverless
nvm use
npm i
cp -a stages/sample.production.yml stages/production.yml
cp -a config/sample.download-schedules.yml config/download-schedules.yml
cp -a config/sample.airports-download-schedules.yml config/airports-download-schedules.yml
cp -a config/sample.apiusage.yml config/apiusage.yml
aws --profile production ssm put-parameter --name maxmindToken --value YourMaxminfToken --type SecureString
# Edit yml files to suite your needs
npm run deploy
# Update manually Route53 to point to the newly created distribution

# Trigger a first time download
./node_modules/.bin/sls -s production invoke -f Download -p events/GeoLite2-ASN.json
./node_modules/.bin/sls -s production invoke -f Download -p events/GeoLite2-City.json
./node_modules/.bin/sls -s production invoke -f Download -p events/GeoLite2-Country.json

Database updates

Updates are run through Cloudwatch schedules events. You can change download times in config/download-schedules.yml

Modify

git clone https://github.com/Spuul/geoip-serverless
cd geoip-serverless
nvm use
npm i

Functions

Download

Triggered from Cloudwatch scheduled event.

  • Fetches the csv-zip and extracts the IP4-Blocks and english names (language can be changed in stages/production.yml)
  • Uploads the files to S3

Prepare

Triggered from S3PutObject event.

  • Converts IP Ranges to Integer ranges
  • Combines ranges and Names to partitioned JSON-Lines documents
  • Uploads the files to S3

Getipinfo

Triggered from api-gateway.

  • Fetches the relevant row using S3-Select from the relevant database and partition

AirportsDownload

Triggered from Cloudwatch scheduled event.

  • Fetches the list of airport codes and stores the ones with a valid IATA code

CloudfrontEdgesPrepare

Triggered from S3PutObject event on aiport codes.

  • Convert airport codes to Cloudfront Edges informations

Resources

ApiGateway

API Gateway is a local gateway, access is granted using x-api-key header.

Cloudfront

Cloudfront caches to response to reduce ApiGateway usage. Cache-Control is in sync with Maxmind's update schedule.