geocoder-api

geocoder-api is RESTFull API that provide support for geocoding operations.

TODO: move migrations into Heroku release phase so app can easily boot

in less than 90s. https://help.heroku.com/LSXQDDSI/why-does-my-java-app-crash-with-an-r10-error

Migration lock problems: https://stackoverflow.com/questions/15528795/liquibase-lock-reasons

Installing

$ git clone https://github.com/devgateway/geocoder-api.git
$ cd geocoder-api
$ mvn clean install package -DskipTests

Compiled jar will be located under target/geocoder-1.0.jar

Configuring

Before compiling you should visit the application.properties file located under src/main/resources folder.

Setting HTTP port

server.port = 8083

Database configuration

spring.datasource.url= jdbc:postgresql://localhost:5432/geocoder
spring.datasource.username=postgres
spring.datasource.password=admin

Important keep the nexts two line without changes.

spring.jpa.hibernate.ddl-auto=update
spring.jpa.generate-ddl=true

Static Files Path

The API can serve static files by setting.

geocoder.ui.path=/opt/geocoder-ui/

Maximum uploaded file size allowed

spring.http.multipart.max-file-size=10MB

Maximum size allowed for multipart/form-data requests.

spring.http.multipart.max-request-size=10MB

Running

To run the api you should pass the jar file to the java command.

$ java -server jar target/geocoder-1.0.jar

Let's assign more memory to the JDK.

$ java -server -Xms1G -Xmx2G -jar target/geocoder-1.0.jar

You can switch application properties file by setting --spring.config.name=prop_name

$ java -server -Xms1G -Xmx2G  -jar target/geocoder-1.0.jar --spring.config.name=prod

First time execution

During the first execution, Open Aid Geocoder API creates new tables and inserts required system data such as countries and IATI codes etc.

order to integrate both systems, you can plug Open Aid Geocoder and AutoGeocoder sharing the same database. During the first execution Manual Coder API will update some of the AutoGeocoder tables and creates additional system tables.

Importing Country Boundaries

Country boundaries are an important piece on the manual coding process. We recommend to use Global Administrative Areas http://www.gadm.org/ as country boundaries source.

In order to incorporate boundaries data you should follow the following steps:

$ wget http://biogeo.ucdavis.edu/data/gadm2.8/gadm28_levels.shp.zip
$ unzip gadm28_levels.gdb.zip
$ cd  gadm28_levels.gdb
$ shp2pgsql -I -s 4326 gadm28_adm2.shp public.boundaries | psql -Upostgres -d geocoder

_* We use admin2.shp since Open Aid Geocoder UI picks up to second admin level.

Opening the Open Aid Geocoder UI

Once API is running, if geocoder.ui.path has been properly set to geocoder-ui dist folder, you should be able to load the Open Aid Geocoder by opening http://localhost:{API_PORT}.

API Endpoints

/filters/all - Shows all apps filters in objects like ‘countries’ and ‘years’. Countries/Years represent all the unique countries/years that we have projects for.
/import: Import a valid IATI XML file. Beside the XML file this endpoint supports parameters such as:
- autoGeocodeAll - Indicates if all the projects will be checked by the auto-geocoder tool.
- autoGeocodeAllWithoutLoc - Indicates that ONLY projects without a location will be checked by the auto-geocoder tool_
- overwriteProjects - If the IATI file contains projects that are already in the system (based on the project identifier) then this parameter indicates if we will ignore those projects or if we want to overwrite them.
/export Exports a valid IATI XML file with all the projects in the system. If we need to filter the export then we can pass an object including:
- text - free text that is searched in all Project’s Narratives.
- countries - a list of ISO2 countries
- years - a list of years
- withNoLocation - Boolean that gets only projects with no location
- pendingVerification - Boolean that gets only projects with pending verification locations
- verifiedLocation - Boolean that gets only projects that have all the locations verified
/projects - exports in JSON format all the projects that matched the received search criteria.
- text - free text that is searched in all Project’s Narratives.
- countries - a list of ISO2 countries
- years - a list of years
- withNoLocation - Boolean that gets only projects with no location
- pendingVerification - Boolean that gets only projects with pending verification locations
- verifiedLocation - Boolean that gets only projects that have all the locations verif
/project/{id} - Request Method GET - This method will return a JSON export with all the critical fields of a Project. The projects is identified by the id received as a parameter
/project/{id} - Request Method PUT - this method will update a Project. All the new fields are received in the following parameter: Activity activity
/project/{id} - Request Method DELETE - this method will delete a particular project received as a parameter
/boundaries/list - exports a full list of all countries boundaries
/boundary - exports a FeatureCollection of the country received as parameter.
/documentref/{locationId} - gets all the documents references that are used to autogeocode a particular location.

Hardware Requirements

We have tested the suite in the following environments

Testing Server:
- OS: Red Hat Enterprise Linux
- CPU: Intel(R) Xeon(R) CPU E5-4640 v2 @ 2.20GHz x 2
- Memory: 8GB Of RAM
Production Server:
- OS: Red Hat Enterprise Linux
- CPU: Intel(R) Xeon(R) CPU E5-4640 v2 @ 2.20GHz x 2
- Memory: 30GB Of RAM
Development Computer 1:
- OS: Windows 10
- CPU: Intel(R) Core(TM) i7-7500U CPU @ 2.70GHz, 2904 Mhz, 2 Core(s), 4 Logical Processor(s)
- Memory: 16GB
Development Computer 2:
- OS: Ubuntu
- CPU: Intel® Core™ i7-3632QM CPU @ 2.20GHz × 8
- Memory: 16GB

Geocoder Suite Technical Guide

For detailed installation instructions please look at the technical guide https://drive.google.com/file/d/1QhGoI_syJq3FqO0lm3Zc7j5ziuWro5TK/view

thadk / geocoder-api