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.

GET

Returns basic information about the API and available endpoints.

Try it out

Response
Headers
Waiting for response...
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.

Public Access

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.

GET

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

Response
Headers
Waiting for response...
Send a request to see the response
Send a request to see response headers

Projects

Retrieve a list of infrastructure projects with optional filtering.

GET /projects

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

sector
subsector
status
year
limit
offset
sort
order
/projects
Response
Headers
Waiting for response...
Send a request to see the response
Send a request to see response headers

Project by ID

Retrieve detailed information for a specific project.

GET /projects/{id}

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

id
/projects/{id}
Response
Headers
Waiting for response...
Send a request to see the response
Send a request to see response headers

Sectors

Retrieve all available sectors.

GET /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

/sectors
Response
Headers
Waiting for response...
Send a request to see the response
Send a request to see response headers

Subsectors

Retrieve all subsectors with optional sector filtering.

GET /subsectors

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

sector
/subsectors
Response
Headers
Waiting for response...
Send a request to see the response
Send a request to see response headers

Statistics

Retrieve aggregated statistics about infrastructure projects.

GET /stats

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

/stats
Response
Headers
Waiting for response...
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";
        }
    }
}