README.md

Table of contents

• Description
• Request and response details
  • JSON Format
  • CSV Format
• Service configuration
  • Deployment
• Examples

Description

IP2Location is used to get location by IP. Datastore is ip2location binary DB file. Service is running in AWS Lambda and receiving requests via AWS API Gateway. ip2loc service can provide JSON and CSV responses.

Service accepts only GET request with query strings.

IP2Location Python lib was used

Request and response details

JSON Format

Query strings:

• ip - Any IPv4 address
• format - json

Fields returned:

• city_name
• country_code
• country_name
• region_name

CSV Format

Query strings:

• ip - Any IPv4 address
• format - csv

Value order:

1. country_code
2. country_name
3. region_name
4. city_name

Service configuration

IP2Location is configured via environment variables.

Next environment variables are required:

• DEBUG - set debug mode. In debug additional logging applied
• DB_FILE - ip2location binary file path related to main func file
• CSV_DELIMITER - Delimiter used for CSV format

For service to operate ip2location DB file must be present in src/db

Deployment

1. Create AWS Lambda with IAM User that have CloudWatch write permissions.

   Code should be zipped from src folder.

   cd src
   zip -r ip2loc.zip .

   AWS Lambda handler main.lambda_handler

2. Set AWS Lambda environment variables (Service configuration)

   Recommended AWS Lambda resource limits:

   • memory_size - 128 mb
   • timeout - 2 seconds

3. Create AWS API Gateway with only root resource.

4. Create GET method AWS API Gateway console with AWS Lambda integration request.

5. Set up propper AWS Lambda permissions to allow API Gateway invocations.

6. Test with examples provided in Examples

Examples

Sample JSON request:

https://example.com/somepath/?ip=113.53.111.32&format=json

Sample JSON response:

{
  "city_name": "Ko Samui",
  "country_code": "TH",
  "country_name": "Thailand",
  "region_name": "Surat Thani"
}

Sample CSV request:

https://example.com/somepath/?ip=113.53.111.32&format=csv

Sample CSV response:

TH;Thailand;Surat Thani;Ko Samui

Local testing

Python version 3.6+ tested only

For service to operate ip2location DB file must be present in src/db

# source env_local
# cd src/
# python3 main.py