Nescrow GAL Codes API Documentation

Getting Started

Welcome

GAL Codes - Addressing re-defined!


Nescrow GAL Codes Logo

Nescrow Solves Addressing needs using 6 Characters GAL Codes to represent every Building in the world using a crowdsourced approach you can Download Nescrow Gal Codes from Google PlayStore here.
The Essence of this Documentation is to describe how you can integrate GAL Codes seamlessly into your existing Platform, Software or Business

  • This API uses HTTP based Calls with json formated responses

API Endpopints

The End point for this version of API is
	   https://nescrow.com.ng/gal/api/v1
	   
All API calls have their respective script to call in the API root for example the GET GAL details endpoint is get_gal.php Hence the URL to call for GET GAL details becomes
https://nescrow.com.ng/gal/api/v1/get_gal.php

For All GAL photos related endpoints, after calling the gal photo retrieveal endpoint, the API returns the base name of the GAL photos relative to the GAL API ROOT
For avoidance of doubt, the GAL photo root is
https://nescrow.com.ng/gal/api/
So if you get a gal dest json field of "galphoto/AKIN_d41d8cd98f00b204e9800998ecf8427ezinsutech.PNG " the location of the file becomes
https://nescrow.com.ng/gal/api/galphoto/AKIN_d41d8cd98f00b204e9800998ecf8427ezinsutech.PNG
	 

For All GAL details related endpoitns after calling the gal details retreival endpoinys, the API returnns the base name of the GAL QR Code relative to the GAL API root For avoidance of doubt, the GAL QR code root is
 https://nescrow.com.ng/gal/api/
So if you get a gal gal_qr json field of "gal_qr_codes/gal_file_0acaaf39879fc7591d41dff4eaf48543.png" the location of the file becomes
https://nescrow.com.ng/gal/api/galphoto/gal_qr_codes/gal_file_0acaaf39879fc7591d41dff4eaf48543.png
	 

Authentication

Authentication is done by passing your api_key and access_token via POST to the respective endpoints you are calling.
You can Generate your Access here
Depending on the method of calling you simply pass
	  api_key = {your API Key}
	  access_token = {your access token}
	  

HTTP Status code

Throughout this API Documentation All API calls can either return a status success or fail ie.
	  "status":1 - means successful request 
	  "status":0 - means failed request
	  
for example below is a sample successful call to an endpoint
 {"status":1,"details":{"gal_code":"4E4-OYP","gal_bar":"","gal_qr":"gal_qr_codes\/gal_file_0acaaf39879fc7591d41dff4eaf48543.png"}}
	  

Pagnitation Rules

Some times a data retreival request may containg alot of fields, to prevent information overload and for more efficient resource management on our side, we pagintize such request and send them in chunks of 20 values. this pagintation is controled by the GET field

	  page
	  
page GET field accepts positive integers
Pagination rules: Wherever the name value “page” is specified in the API documentation – the page request from 1,2,3 …. Not including the field "page" in requests, 1 is assumed, to fetch values from 20 -40, this field will be set to 2 , 40 -60, this field will be sent to 3 , … an so on, This is the pagination rule for this API


GET GAL Details API

About: This end point is to request for the full gal related information about a GAL code identified by its gal_id
End Point:
https://nescrow.com.ng/gal/api/v1/get_gal.php
Name value Pair
gal_code – The GAL code text of the gal code,
Response
status – this is the status of the api call can be two values
1 – for a successful call getting this value, you can tell user of success and show appropriate success message
0 – the request failed due to some reasons in the details field getting this value, you can tell user of Failure and show appropriate Failure message
details - this gives further details with respect to the API call, in case of a failed call, you can use this to generally have an idea of why the call failed example details value include
  • “success” - Upon a successful call (status of 1) of this endpoint, the data field will contain the below
    data - upon successful response the API sends all the GAL details using this data field
    • gal_id - don’t know whi I added this, but it’s the same data that was used in reteiving the data in the first place
    • lat – the latitude for the latlong of that gal code
    • long1 – the longitude for the latlong of that gal code
    • gal_text - the generated gal code for that latlong
    • gal_bar – the image link to the bar code of the galcode, this link is relative to the API root, so append the api root should you need this image to show.
    • gal_qr - the image link to the QR of the galcode, this link is relative to the API root, so append the api root should you need this image to show.
    • when1 – the date time when the GAL code was generated
    • user_comment – if the user added a comment when generating the code for easy identification of location by the user, here you have the comment.
    • gal_address_json – this is the json encoded format of the gal address , the json must contain all the information about the address in the below
      • Building number - this is the number of building with that GAL code
      • Street name - the name of the street where that GAL Code can be found
      • Area - the name of the area where that GAL code can be found
      • City - the name of the city where that GAL code can be found
      • Local Government area - the name of the Local governemnt where that GAL code can be found
      • the name of the state where that GAL code can be found
      • the name of the country where that GAL code can be found
    • category – the category of the building/location as specified by the user example, is museum, church, office, etc
    • example (API document version is 1.01 for the below example).
      {"status":1,"details":"success","data":{"gal_id":"37","lat":"7","long1":"5","gal_text":"4E4-OYP","gal_bar":"","gal_qr":"gal_qr_codes\/gal_file_0acaaf39879fc7591d41dff4eaf48543.png","when1":"2015-10-20 16:25:16","user_comment":"Grandpa place"}}
    • “error getting gal code or gal does not exist” – The GAL code doesn’t exist if this error is reteived multiple times, it signifies an error retrieving the gal code. • “Integration error, one or more compulsory fields omitted” - This means one, more or all of the compulsory parameters have been omitted.
    • Compact View
    <script>
    	$(document).ready(function (){
    	$('#CompactView').opineo('results.php',
        	    {curvalue:3, view: 'compact',
        	    animation_speed: 'super'});
    	})
    </script>
    • Mini View
    <script>
        $(document).ready(function (){
        $('#MiniView').opineo('results.php', {curvalue:0, view: 'mini', callback: myCallback});
        })	
    </script>

    Animation Style

    • Slow
    <script>
        $(document).ready(function (){
        $('#opineo').opineo('results.php', {curvalue:0, view: 'mini', animation_speed:'slow'});
        })	
    </script> 
    • Medium
    <script>
        $(document).ready(function (){
        $('#opineo').opineo('results.php', {curvalue:0, view: 'mini', animation_speed:'mild'});
        })	
    </script> 
    • Fast
    <script>
        $(document).ready(function (){
        $('#opineo').opineo('results.php', {curvalue:0, view: 'mini', animation_speed:'fast'});
        })	
     </script>
    • Super Fast
    <script>
        $(document).ready(function (){
        $('#opineo').opineo('results.php', {curvalue:0, view: 'mini', animation_speed:'super'});
        })	
    </script>
    • Ultra Fast
     <script>
        $(document).ready(function (){
        $('#opineo').opineo('results.php', {curvalue:0, view: 'mini', animation_speed:'ultra fast'});
        })	
    </script> 

    Bars Text

    • Show
    <script>
        $(document).ready(function (){
        $('#opineo').opineo('results.php', {curvalue:0, view: 'mini', votes_label:true});
        })	
    </script>
    • Hide
    <script>
        $(document).ready(function (){
        $('#opineo').opineo('results.php', {curvalue:0, view: 'mini', votes_label:false});
        })	
     </script>

    Vote Counter

    • Show
    <script>
        $(document).ready(function (){
        $('#opineo').opineo('results.php', {curvalue:0, view: 'mini', show_votes_counter:true});
        })	
    </script> 
    • Hide
    <script>
        $(document).ready(function (){
        $('#opineo').opineo('results.php', {curvalue:0, view: 'mini', votes_label:false});
        })	
    </script>

    Rating Icons

    • Colored
    • Grey

    Rating Titles

    • Text For First Star
    <script>
        $(document).ready(function (){
        $('#opineo').opineo('results.php', {curvalue:0, view: 'mini', star_1_text:'Hate It'});
        })	
    </script>
    • Text For Second Star
    <script>
        $(document).ready(function (){
        $('#opineo').opineo('results.php', {curvalue:0, view: 'mini', star_2_text:'Don't Like It'});
        })	
    </script> 
    • Text For Third Star
    <script>
        $(document).ready(function (){
        $('#opineo').opineo('results.php', {curvalue:0, view: 'mini', star_1_text:'Its OK'});
        })	
    </script>
    • Text For Fourth Star
    <script>
        $(document).ready(function (){
        $('#opineo').opineo('results.php', {curvalue:0, view: 'mini', star_1_text:'Like It'});
        })	
    </script>
    • Text For Fifth Star
    <script>
        $(document).ready(function (){
        $('#opineo').opineo('results.php', {curvalue:0, view: 'mini', star_1_text:'Love It'});
        })	
    </script>

    Bar Colors

    • Colors of Red Bar
    • Colors of Yellow Bar
    • Colors of Green Bar
  • If you require further information on the API please feel free to contact us at support @ nescrow.com.ng