PIDA Infrastructure Projects API
Welcome to the official API documentation for the Programme for Infrastructure Development in Africa (PIDA) projects database. This API provides programmatic access to infrastructure project data across Africa.
Returns basic information about the API and available endpoints.
Try it out
Send a request to see the response
Send a request to see response headers
Authentication
Currently, the API is publicly accessible without authentication. No API key is required to access the endpoints.
For production use, we recommend implementing rate limiting on your server to prevent excessive usage.
Response Format
All API responses are returned in JSON format. Successful requests will return a 200 OK
status code, while errors will return appropriate status codes (400
, 404
, 500
, etc.) with an error message in the response body.
Success Response
{
"name": "PIDA Infrastructure Projects API",
"version": "1.0.0",
"description": "API for accessing PIDA project data",
"endpoints": [
// Endpoints information...
]
}
Error Response
{
"error": "Invalid endpoint"
}
HTTP Status Codes
Status Code | Description |
---|---|
200 |
OK - The request succeeded |
400 |
Bad Request - Invalid parameters |
404 |
Not Found - The specified resource could not be found |
500 |
Internal Server Error - Something went wrong on the server |
API Info
Get basic information about the API and available endpoints.
Returns basic information about the API, including version, description, and available endpoints.
Example Response
{
"name": "PIDA Infrastructure Projects API",
"version": "1.0.0",
"description": "API for accessing Programme for Infrastructure Development in Africa (PIDA) project data",
"endpoints": [
{
"path": "/api/projects",
"method": "GET",
"description": "Get all projects with optional filtering",
"parameters": {
"sector": "Filter by sector ID",
"subsector": "Filter by subsector ID",
"status": "Filter by status ID",
"year": "Filter by year",
"referencePlan": "Filter by reference plan ID",
"limit": "Limit number of results (default: 100)",
"offset": "Offset for pagination (default: 0)",
"sort": "Field to sort by (default: id)",
"order": "Sort order (asc or desc, default: asc)"
}
},
{
"path": "/api/projects/{id}",
"method": "GET",
"description": "Get details for a specific project by ID"
},
// Other endpoints...
]
}
Try it out
Send a request to see the response
Send a request to see response headers
Projects
Retrieve a list of infrastructure projects with optional filtering.
Returns a paginated list of infrastructure projects. Various query parameters can be used to filter the results.
Query Parameters
Parameter | Type | Description | Default |
---|---|---|---|
sector | integer | Filter by sector ID | - |
subsector | integer | Filter by subsector ID | - |
status | integer | Filter by status ID | - |
year | integer | Filter by project creation year | - |
referencePlan | integer | Filter by reference plan ID | - |
limit | integer | Number of results to return | 100 |
offset | integer | Offset for pagination | 0 |
sort | string | Field to sort by (id, project_name, sector_id, subsector_id, capex_cost, year_created) | id |
order | string | Sort order (asc, desc) | asc |
Example Response
{
"total": 42,
"limit": 10,
"offset": 0,
"count": 10,
"data": [
{
"id": 234,
"project_name": "Trans-Saharan Highway",
"sector": {
"id": 19,
"name": "Transport"
},
"subsector": {
"id": 101,
"name": "Roads"
},
"status": {
"id": 4,
"name": "Implementation"
},
"stage": {
"id": 3,
"name": "Construction"
},
"coordinates": {
"lat": 5.7,
"lng": 13.2
},
"capex_cost": 450,
"start_date": "Jan 2021",
"updated_date": "Nov 2023",
"reference_plan": "PIDA PAP 2",
"year": 2021
},
// More projects...
]
}
Try it out
Send a request to see the response
Send a request to see response headers
Project by ID
Retrieve detailed information for a specific project.
Returns detailed information about a specific project, including all available fields, relationships, and geographical data.
Path Parameters
Parameter | Type | Description | Required |
---|---|---|---|
id | integer | Project ID | Yes |
Example Response
{
"id": 234,
"project_name": "Trans-Saharan Highway",
"sector": {
"id": 19,
"name": "Transport"
},
"subsector": {
"id": 101,
"name": "Roads"
},
"status": {
"id": 4,
"name": "Implementation"
},
"stage": {
"id": 3,
"name": "Construction"
},
"coordinates": {
"lat": 5.7,
"lng": 13.2
},
"location_map": "LINESTRING(5.7 13.2, 6.2 14.1, 7.5 15.3)",
"capex_cost": 450,
"preparation_cost": 50,
"operation_cost": 25,
"date_created": "2021-01-15",
"date_updated": "2023-11-21",
"description": "Detailed project description text...",
"summary": "Project summary text...",
"revenue_model": "Toll-based revenue with government subsidies",
"project_risk": "Moderate risk due to cross-border operations",
"pida_code": "TSH-2021-234",
"alternative_names": "Trans-Sahel Corridor, North-South Connection",
"reference_plans": [
{
"id": 2,
"name": "PIDA PAP 2"
}
],
"stakeholders": [
{
"id": 45,
"name": "African Development Bank",
"acronym": "AfDB"
},
{
"id": 67,
"name": "Economic Community of West African States",
"acronym": "ECOWAS"
}
],
"countries": [
{
"id": 12,
"name": "Nigeria"
},
{
"id": 35,
"name": "Niger"
},
{
"id": 4,
"name": "Algeria"
}
],
"beneficiary_countries": [
{
"id": 12,
"name": "Nigeria"
},
{
"id": 35,
"name": "Niger"
},
{
"id": 4,
"name": "Algeria"
},
{
"id": 22,
"name": "Mali"
}
],
"completion_percentage": 65.5
}
Try it out
Send a request to see the response
Send a request to see response headers
Sectors
Retrieve all available sectors.
Returns a list of all available sectors for infrastructure projects.
Example Response
[
{
"id": 19,
"name": "Transport"
},
{
"id": 20,
"name": "Energy"
},
{
"id": 21,
"name": "ICT"
},
{
"id": 22,
"name": "Water"
}
]
Try it out
Send a request to see the response
Send a request to see response headers
Subsectors
Retrieve all subsectors with optional sector filtering.
Returns a list of all available subsectors, optionally filtered by parent sector.
Query Parameters
Parameter | Type | Description | Required |
---|---|---|---|
sector | integer | Filter by parent sector ID | No |
Example Response
[
{
"id": 101,
"name": "Roads",
"sector_id": 19
},
{
"id": 102,
"name": "Railways",
"sector_id": 19
},
{
"id": 103,
"name": "Airports",
"sector_id": 19
},
{
"id": 104,
"name": "Ports",
"sector_id": 19
},
{
"id": 105,
"name": "Urban Transit",
"sector_id": 19
}
]
Try it out
Send a request to see the response
Send a request to see response headers
Statistics
Retrieve aggregated statistics about infrastructure projects.
Returns aggregated statistics about projects, including totals, sector breakdowns, and yearly distribution.
Example Response
{
"total_projects": 187,
"total_countries": 54,
"total_stakeholders": 123,
"total_investment": 93250.75,
"by_sector": [
{
"id": 19,
"name": "Transport",
"count": 82,
"total_cost": 45350.25
},
{
"id": 20,
"name": "Energy",
"count": 65,
"total_cost": 35780.5
},
{
"id": 21,
"name": "ICT",
"count": 22,
"total_cost": 5620
},
{
"id": 22,
"name": "Water",
"count": 18,
"total_cost": 6500
}
],
"by_status": [
{
"id": 4,
"name": "Implementation",
"count": 87
},
{
"id": 3,
"name": "Feasibility",
"count": 45
},
{
"id": 1,
"name": "Planning",
"count": 35
},
{
"id": 5,
"name": "Operational",
"count": 20
}
],
"by_year": [
{
"year": 2019,
"count": 32
},
{
"year": 2020,
"count": 45
},
{
"year": 2021,
"count": 56
},
{
"year": 2022,
"count": 34
},
{
"year": 2023,
"count": 20
}
]
}
Try it out
Send a request to see the response
Send a request to see response headers
Client Examples
Examples of how to use the PIDA API with different programming languages.
JavaScript Example
// Fetch all transport projects
async function getTransportProjects() {
try {
const response = await fetch('/api/projects?sector=19');
const data = await response.json();
console.log(`Found ${data.total} transport projects`);
// Do something with the data
data.data.forEach(project => {
console.log(`${project.project_name} - ${project.capex_cost} million`);
});
return data;
} catch (error) {
console.error('Error fetching transport projects:', error);
}
}
// Get detailed project information
async function getProjectDetails(projectId) {
try {
const response = await fetch(`/api/projects/${projectId}`);
if (!response.ok) {
throw new Error(`HTTP error! Status: ${response.status}`);
}
const project = await response.json();
console.log(`Details for ${project.project_name}:`, project);
return project;
} catch (error) {
console.error(`Error fetching project ${projectId}:`, error);
}
}
// Get statistics
async function getProjectStatistics() {
try {
const response = await fetch('/api/stats');
const stats = await response.json();
console.log(`Total projects: ${stats.total_projects}`);
console.log(`Total investment: $${stats.total_investment} million`);
// Create a chart of projects by sector
const sectorLabels = stats.by_sector.map(s => s.name);
const sectorCounts = stats.by_sector.map(s => s.count);
// Example with Chart.js
createSectorChart(sectorLabels, sectorCounts);
return stats;
} catch (error) {
console.error('Error fetching statistics:', error);
}
}
PHP Example
<?php
// Fetch all energy projects
function getEnergyProjects() {
$url = 'http://yourserver.com/api/projects?sector=20';
$response = file_get_contents($url);
if ($response === false) {
return ['error' => 'Failed to fetch data'];
}
return json_decode($response, true);
}
// Get detailed project information
function getProjectDetails($projectId) {
$url = "http://yourserver.com/api/projects/{$projectId}";
$response = file_get_contents($url);
if ($response === false) {
return ['error' => 'Failed to fetch project details'];
}
return json_decode($response, true);
}
// Get statistics
function getProjectStatistics() {
$url = 'http://yourserver.com/api/stats';
$response = file_get_contents($url);
if ($response === false) {
return ['error' => 'Failed to fetch statistics'];
}
return json_decode($response, true);
}
// Example usage
$energyProjects = getEnergyProjects();
if (isset($energyProjects['error'])) {
echo "Error: " . $energyProjects['error'];
} else {
echo "Found " . count($energyProjects['data']) . " energy projects\n";
// Display first project
if (!empty($energyProjects['data'])) {
$firstProject = $energyProjects['data'][0];
echo "First project: " . $firstProject['project_name'] . "\n";
// Get detailed information
$projectDetails = getProjectDetails($firstProject['id']);
if (!isset($projectDetails['error'])) {
echo "Project description: " . $projectDetails['description'] . "\n";
}
}
}