Warning
This project was created mainly to illustrate a use case for S3-Select.
This project is no longer used in production and therefore isn't maintained anymore.
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:
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
- A Domain hosted in Route53
- An ACM certificate in us-east-1 configured for the domain you will use
- nvm
- aws-cli
- A Maxmind License Key
git clone https://github.com/DanielMuller/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 YourMaxmindToken --type SecureString
# Edit yml files to suite your needs
# AWS Profile used by CLI
# Region to deploy to (same as your bucket)
# The domain name to be used
# Your domain's HostedZoneId
# Your Certificate ARN
# Your Bucket name
# The prefix to be used to store your data
npm run deploy
# Take note of the ApiKeys generated, you will need them to call the service
# Trigger a first time download
sls -s production invoke -f Download -p events/GeoLite2-ASN.json
sls -s production invoke -f Download -p events/GeoLite2-City.json
sls -s production invoke -f Download -p events/GeoLite2-Country.json
sls -s production invoke -f AirportsDownload
# Wait for 5 to 10 minutes to allow the background process to finish
Updates are run through Cloudwatch schedules events. You can change download times in config/download-schedules.yml
git clone https://github.com/DanielMuller/geoip-serverless
cd geoip-serverless
nvm use
npm i
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
Triggered from S3PutObject event.
- Converts IP Ranges to Integer ranges
- Combines ranges and Names to partitioned JSON-Lines documents
- Uploads the files to S3
Triggered from api-gateway.
- Fetches the relevant row using S3-Select from the relevant database and partition
Triggered from Cloudwatch scheduled event.
- Fetches the list of airport codes and stores the ones with a valid IATA code
Triggered from S3PutObject event on aiport codes.
- Convert airport codes to Cloudfront Edges informations
API Gateway is a local gateway, access is granted using x-api-key header.
Cloudfront caches to response to reduce ApiGateway usage. Cache-Control is in sync with Maxmind's update schedule.