Skip to content

Home

Jump to bottom Edit New page
Sebastian Dimunzio edited this page Mar 8, 2016 · 20 revisions

Open Aid Geocoder

This tool allows users to attach geographical information to existing aid projects in an aid information management system (AIMS). The project supports

  • Hot reloading React components;
  • Error handling inside component render() function;
  • Error handling for syntax errors

Demo

http://devgateway.github.io/open-aid-geocoder

Development

####Development Build

npm install gulp -G
npm install 
gulp

####Production build

npm install gulp -G
npm install 
gulp build-prod

####gh_pages deployment

gulp deploy

Running gulp without target will build the project using web pack development configuration and will start an express web server. Run gulp build-prod to build a distributable application. Run gulp deploy to push dist folder into gh_pages branch

API

The API provides a set of endpoints exposed over HTTP protocol using Javascript Object Notation (JSON). Each endpoint should follow a standard implementation, please refer to https://github.com/WhiteHouse/api-standards.

####Project search Perform project search across the database.

  • URL: /projects

  • HTTP Method: GET,

  • Content Type: 'application/json'

  • Returns: The total records counts and and an array of projects.

  • Query string parameters:

  • f: String Text to search

  • withloc: Boolean, Specify locations filters, true to filter only projects having locations field or false for the opposite logic, keep it empty to disable this filter

  • sort: String Specify the sort field

  • order: Numeric 1 or -1 to specify an ascending or descending sort respectively.

  • skip: Numeric _Specify number of documents to skip.

  • limit: Numeric Specify the maximum number of documents to return

  • e.g.:

{
  "count":3,
  "projects":[
    {
      "project_id":2390082,
      "title":"BPD Institutional Support Study (Grant)",
      "long_description":"Will be used to finance the entire foreign exchange cost of the study.....",
      "country":{
        "id":110593497,
        "name":"Mozambique",
        "iso3":"MOZ"
      }
    },
    {
      "project_id":2165211,
      "title":"Beira Corridor Health Project",
      "long_description":"The ADF loan will be used to finance 90 per cent of the total cost of the project while the remaining 10 per cent will be provided by the Government of Mozambique.",
      "country":{
        "id":110593497,
        "name":"Mozambique",
        "iso3":"MOZ"
      }
    },
    {
      "project_id":635642,
      "title":"Cashew Rehabilitation Project",
      "long_description":"The objective of the project is to increase the production of raw cashew nuts ...",
      "country":{
        "id":110593497,
        "name":"Mozambique",
        "iso3":"MOZ"
      },
      "locations":[
        {
          "name":"Provincia de Manica",
          "id":112211328,
          "description":"The location is within a first order administrative division (ADM1), such as a province, state or governorate, but the location within the ADM1 is unknown.",
          "activityDescription":"To (a) increase the number and raise the quality of graduates at the undergraduate and graduate levels",
          "country":{
            "ISO2":"MZ",
            "ISO3":"MOZ",
            "name":"Mozambique"
          },
          "admin1":{
            "id":2115,
            "name":"Manica"
          },
          "geometry":{
            "type":"Point",
            "coordinates":[
              33.5,
              -19
            ]
          },
          "featureDesignation":{
            "code":"PPL",
            "name":"populated place"
          },
          "locationClass":{
            "code":"2",
            "name":"Populated Place"
          },
          "exactness":{
            "code":"1",
            "name":"Exact"
          }
        }
      ]
    }
  ]
}

####Project details Provide access to project information by passing a project id parameter.

  • URL: /project/{id}
  • HTTP Method: GET,
  • Content Type: 'application/json'
  • Returns: Project Document.
  • URL Parameters:
  • id: NumericProject id
  • e.g.:
{
  "project_id":635642,
  "title":"Cashew Rehabilitation Project",
  "long_description":"The objective of the project is to increase the production of raw cashew nuts ...",
  "country":{
    "id":110593497,
    "name":"Mozambique",
    "iso3":"MOZ"
  },
  "locations":[
    {
      "name":"Provincia de Manica",
      "id":112211328,
      "description":"The location is within a first order administrative division (ADM1), such as a province, state or governorate, but the location within the ADM1 is unknown.",
      "activityDescription":"To (a) increase the number and raise the quality of graduates at the undergraduate and graduate levels",
      "country":{
        "ISO2":"MZ",
        "ISO3":"MOZ",
        "name":"Mozambique"
      },
      "admin1":{
        "id":2115,
        "name":"Manica"
      },
      "geometry":{
        "type":"Point",
        "coordinates":[
          33.5,
          -19
        ]
      },
      "featureDesignation":{
        "code":"PPL",
        "name":"populated place"
      },
      "locationClass":{
        "code":"2",
        "name":"Populated Place"
      },
      "exactness":{
        "code":"1",
        "name":"Exact"
      }
    }
  ]
}

####Update Project Updates the project information with the latest changes performed by the Geocoder tool.

  • URL: /project/{id}
  • HTTP Method: POST,
  • Content Type: 'application/json'
  • URL Parameters:
  • id: NumericProject id
  • Post Data: Project Document.

_The tool only updates the locations array by adding new coded locations or updating exiting ones.

If an existing location has been updated, the new values are set to the location properties, and an additional status field is added indicating the status is UPDATED.

If an existing location has been deleted a status field is added indicating the status is DELETED.

If a new location has been added the status field is set to NEW.

##Security ###Existing Server Side Applications This application has been created with the purpose of being embedded in an existing web system, the existing system responsible to host the geocoder should provide the security context. ###REST Client The application doesn't implement any access control/authorization pattern. If this application will be used as a REST client the access control/authorization features should be implemented. #####Notes The API provided with the tool should be used only for development purpose.

Integration

Open Aid Geocoder is a javascript-based application. The process for integrating the tool within an existing system will vary depending on the nature of the system to be integrated with, but the below outlines a general process.

#####Get the tool.

	git clone https://github.com/devgateway/open-aid-geocoder.git
	cd open-aid-geocoder
	npm install gulp –G
	npm install 
	gulp build-prod

The distributable version of the tool will be located under the dist folder.

#####Copy files. Copy the “dis”t folder into your system path.

#####Add a new web page. Add a new web page within you system with the following html code.

<html>
  <head>
    <title>Geocoder</title>
  	
  <link href="/PATH_TO_GEOCODER_DIST_FOLDER/main.css" rel="stylesheet"></head>
  <body>
    <div id='root'> </div>
   
  <script src="/PATH_TO_GEOCODER_DIST_FOLDER/bundle.js"></script></body>
</html>

#####Configure. A default configuration file is provided and can be found under dist/conf folder. Some of the configuration values are based on the environment, the system decides if the environment is production or development based on the location URL. If the location URL is localhost development values are used. The conf folder path should be located in the same path of the new web page.

#####Connect. The existing system should provide two JSON based endpoints, please read the API section for more info. The following configuration parameters should be updated in order to allow the tool to use the end-points

 "API_BASE_URL":"BASE_END_POINTS_URL",
 "PROJECT_LIST_END_POINT": "URL_TO_PROJECT_SEARCH_END_POINT",
 "PROJECT_END_POINT": URL_TO_PROJECT__END_POINT"

License

Copyright 2015-2016 Development Gateway

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Do not hesitate to contact us http://developmentgateway.org or [email protected]

Add a custom sidebar
Clone this wiki locally