Using the Farmland Parcelization API

Updated 11 December 2020


Public API Key

ADSS=23232AD=ASDIO293-MLK23290-23AD.235DS554S5_4409IODSO

Retreive A Single Parcelized AGC

The code snippet below shows how to retreive parcelized AGC data from the database using an asynchronous fetch API GET request. It is implemented in ES6/ES2017 JavaScript, and uses object-oriented programming concepts.

By passing the agcID as an argument, it returns a single parcelized AGC from the database in a promise.

// Set up the API call function
async function getParcelizedAgc(agcID) {
	try {
		const apiResponse = await fetch(`https://agcfarmlands.herokuapp.com/api/v1/parcelized-agcs/parcelized-agc/?${agcID}`);
		const data = await apiResponse.json();
		return data;
	} 
	catch (error) {
		console.error(error.message);
	};
};

// Execute the API call
getParcelizedAgc('unique-agc-id-6880561')
	.then(function(data) {
		console.log(JSON.stringify(data));
		}
	);

Retreive All the Parcelzied AGCs


// Set up the API call function
async function getAllParcelizedAgcs() {
	try {
		const apiResponse = await fetch(`https://agcfarmlands.herokuapp.com/api/v1/parcelized-agcs/`);
		const data = await apiResponse.json();
		return data;
	} 
	catch (error) {
		console.error(error.message);
	};
};

// Execute the API call
getAllParcelizedAgcs()
	.then(function(data) {
		console.log(JSON.stringify(data));
		}
	);

Render the Parcelized Plots Preview MapNew!

Each subsequent parcelized AGC payload retreived from the endpoint will now contain a unique string hash that is required to construct a URL that renders the preview map.

Get that string by reading the "properties.preview_map_url_hash" field. Here's a sample JSON snippet from an API call to the parcelized AGCs endpoint-

{
	"status": "success",
	"data": {
		"parcelizedAgcData": {
			"properties": {
				"agc_id": "AGCABI000010",
				"agc_extended_name": "Agc Nosa 7",
				"agc_location": "ABA,Aba South,Abia",
				"num_farmers": 10,
				"agc_area": 50.6404559187225,
				"total_allocation": 45,
				"unused_land_area": 4.417271065696374,
				"preview_map_url_hash": "XAWXEACGEBVLGDRACUGOZYBSZTCKHMMDHOYVAPRWKXRNJVWXHXZH..."
			},
			"type": "FeatureCollection",
			"_id": "5fce88c3071dac0c0c924f7d",
			"features": [ ... ]
		}
	}
}

For security, the url hash string might change periodically. Therefore, before presenting the preview map link to the user, ALWAYS query the API to obtain the most recent hash string. Do not save the string in a variable and expect it to work at a later date.

Construct the preview map url using the hash string like so-

// `https://agcfarmlands.herokuapp.com/parcelized-agc/?${preview_map_url_hash}`

https://agcfarmlands.herokuapp.com/parcelized-agc/?XAWXEACGEBVLGDRACUGOZYBSZTCKHMMDHOYVAPRWKXRNJVWXHXZHUMXTYTILBBMY

Please note that for all the previously parcelized test AGCs, the preview map URLs that included the AGC IDs have now all been deprecated, and will therefore no longer work.


Sending AGC data to the DB (using the fetch API)

The snippet below shows how to persist AGC JSON data (using the GEOJSON standard) to the database using an asynchronous fetch API POST request.

// The API url
const URL = "https://agcfarmlands.herokuapp.com/api/v1/agcs";

// SEE SAMPLE AGC DATA BELOW
const agcJSONData = {"type":"Feature","properties":{"agc_id":"NIRSALAGCAD0001","extended_name":"Nasarawa Maize Growers AGC","location":"Gora, Nasarawa State","agc_president":"farmer_id","governance_structure":{"president":"farmer_id","vice_president":"farmer_id","secretary":"farmer_id"},"agc_details":{"primary_crop":"maize","has_irrigation":true,"has_power":false,"is_flood_prone":false,"has_processing":true,"has_road_access":true},"farmers":[{"farmer_id":"NIRSALAGCAD0001-001","first_name":"Mohammed","last_name":"Sadiq","allocation":2.3},{"farmer_id":"NIRSALAGCAD0001-002","first_name":"Emmanuel","last_name":"James","allocation":2.7}]},"geometry":{"type":"Polygon","coordinates":[[[7.47565314173,10.6277613686],[7.47883088886,10.629113406],[7.48022530227,10.6286972177],[7.48148929327,10.62825697355],[7.48148929327,10.62684100435],[7.48127471655,10.62500916477],[7.48115234076,10.62320202895],[7.48116441071,10.62199067517],[7.479043453931,10.6220631719],[7.47703313827,10.62150000302],[7.4767635762,10.624850332335],[7.47565314173,10.6277613686]]]}}

// Set up the API call function
async function sendAgcData() {
   try {
      await fetch(URL, {
         method: "POST",
         headers: {
            'Accept': 'application/json, text/plain, */*',
            'Content-Type': 'application/json'
         },
         // credentials: [ YOUR_API_KEY ], // *** NOT YET IMPLEMENTED   
         body: JSON.stringify(agcJSONData)
      });
   }
   catch(error) {
      console.log(error.message);
   };
};

// Execute the API call
sendAgcData()
   .then(function(apiResponse) {
         // Do whatever with the API response
         return apiResponse.json();
      }
   ).then(function(data) {
      console.log(data)
   });

Sending AGC data to the Database (using an XML HTTP Request)

The snippet below shows an alternate method to persist AGC JSON data to the database using XMLHttpRequest().

function sendAgcData() {

   // SEE SAMPLE AGC DATA BELOW
   const agcJSONData = { ... };

   const http = new XMLHttpRequest()

   http.open('POST', 'https://agcfarmlands.herokuapp.com/api/v1/agcs/')
   http.setRequestHeader('Content-type', 'application/json')
   http.send(agcJSONData) // Make sure to stringify

   http.onload = function() {
      // Do whatever with the API response
      console.log(http.responseText)
   };
};

Sample AGC JSON Data Structure

Each AGC payload is a GEOJSON FeatureCollection, that contains just ONE Feature.

The DB insertion will fail if the 'agc_id', 'extended_name', 'location', and/or 'farmers' fields are missing from the JSON payload, or if an AGC with the same 'agc_id', 'extended_name', and/or coordinates already exists in the database. Those first 4 fields in 'properties' are REQUIRED.

The total hectares allocated to the farmers must not exceed the AGC land area.

{
	{
		"type": "FeatureCollection",
		"properties": {
			"agc_id": "AGCABJ002B",
			"extended_name": "Kubwa Sugarcane AGC",
			"location": "Kubwa, FCT Abuja",
			"farmers": [
				{
					"farmer_id": "AGCABJ002B-01",
					"first_name": "Taofeek",
					"last_name": "Usman",
					"farmer_photo": "", // Base64 buffer
					"farmer_photo_url": "https://...",
					"allocation": 3.9,
				},
				{
					"farmer_id": "AGCABJ002B-02",
					"first_name": "Samuel",
					"last_name": "Zogonda",
					"farmer_photo": "", // Base64 buffer
					"farmer_photo_url": "https://...",
					"allocation": 3
				},
				{
					"farmer_id": "AGCABJ002B-03",
					"first_name": "Ilyasu",
					"last_name": "Umar",
					"farmer_photo": "", // Base64 buffer
					"farmer_photo_url": "https://...",
					"allocation": 2.3
				}
			]
		},
		"features": [
			{
				"type": "Feature",
				"properties": {
					"shape": "Rectangle",
					"name": "Unnamed Geoman Layer",
					"category": "default"
				},
				"geometry": {
					"type": "Polygon",
					"coordinates": [
						[
							[-74.009534, 40.715192],
							[-74.007089, 40.715192],
							[-74.007089, 40.716753],
							[-74.009534, 40.716753],
							[-74.009534, 40.715192]
						]
					]
				},
				"id": "1dc64de0-3678-4c07-acfd-9388beeb0080"
			}
		]
	}

}