Neat Geo IP Documentation

This page consists of two subsections which are
Project structure
API documentation

Project structure

All the details about the project structure including source code explanation can be found here.

The project is developed on Spring Boot which is suitable for making stand-alone and agile development. In below you can see the structure of this project.

├── db
│   └── GeoLite2-City.mmdb
├── pom.xml
├── sh
│   └──
└── src
    └── main
       └── java
          └── com
              └── madadipouya
                  └── neatgeoip
                      ├── rest
                      │   ├──
                      │   └──
                      ├── pojo
                      │   └──
                      ├── service
                      │   ├──
                      │   └──
                      └── util
                        └── loader

As you can see the project structure is quite simple and straightforward.

db folder

db folder and its file used for looking up the country of the IP address. The database file belongs to MaxMind and is getting updated automatically monthly.

sh folder

sh folder contains file which is specific to the Openshift environment. Basically the script runs monthly to remove database file and restart the application, so the newly updated database will be downloaded. Basically, once the application started, it looks for the database file and if it cannot be found, it will download from MaxMind repository.

src folder

src folder contains the logic and source code of the service. In the following section the purpose of each source code is described in brief. starts Spring Boot application. refers to service at "/getCountry" which looks up for the country of the given IP address. refers to service at "/" which redirects user to Neat Geo IP Github page. is the content of the service which returns to the user. The content includes name (countryName), isoCode, name of the country in other languages (German, Russian, Portuguese [Brazil], Japanese, English, French, Chinese, and Spanish). The final parameter is error in which demonstrates occurred error in the API call. is an interface to get the country name of the IP. is the implementation of which utilizes MaxMind library as. contains the logic of loading the database file based on environment application running. If the database file exists in the local repository ("/db" folder), it uses the file, otherwise, it attempts to download the file from MaxMind server and unzip it as well. The logic of this class is optimized for Openshift and usual normal environment. Keep note that the database file is loaded into memory, if your instance has shortage of the memory, comment `line 57` in

API documentation

This section describes how to use and call the Neat Geo IP Rest API.

API description

Basically Neat Geo IP provides only one API to use. The API method is getCountry which requires ip parameter. The API returns a JSON string as response.

The API URL is located at :

To call the API use UTF-8. For instance,

Consequently when you call the above API method, you get similar response to following :



A sample API call of getCountry method for the IP "".

The response of the API call :


If the location cannot be retrieved "Country not found!" error will be returned in JSON response.

   "errors":["Country not found!"]

This page is maintained by kasramp
Hosted on GitHub Pages — Theme by orderedlist