A comprehensive REST API for Philippine Government Budget Data (NEP/GAA 2020-2026) built on a Neo4j graph database with full UACS dimension linking and hierarchical relationships.

A production-ready, open-source API for Philippine government budget transparency built with NestJS, Neo4j, and TypeScript. This API provides programmatic access to 6.8+ million budget records totaling ₱106.9 trillion with comprehensive filtering, aggregation, year-over-year comparisons, and hierarchical analytics.

• ✅ Complete Budget Data: NEP/GAA records from 2020-2026
• ✅ Hierarchical Structures: Full organizational and expense classification hierarchies
• ✅ NEP vs GAA Comparisons: Built-in comparison analytics
• ✅ Geographic Coverage: Regional, provincial, and municipal breakdowns
• ✅ UACS Compliant: Following Unified Accounts Code Structure standards
• ✅ Graph Database: Complex relationship queries via Neo4j
• ✅ REST API: Clean, well-documented endpoints
• ✅ TypeScript: Full type safety and IDE support

• Node.js 20+
• Neo4j Database 5.x with BetterGovPH budget data loaded
• Yarn package manager

Note: The Neo4j database must be pre-populated with budget data from the open-budget-data repository. See Data Source section below.

# Clone the repository
git clone https://github.com/bettergovph/open-budget-api.git
cd open-budget-api

# Install dependencies
yarn install

# Configure environment
cp .env.example .env
# Edit .env with your Neo4j credentials and configuration

# Development mode (with hot reload)
yarn start:dev

# Production mode
yarn build
yarn start:prod

• API Base URL: http://localhost:3000/api/v1
• Swagger Documentation: http://localhost:3000/api/docs
• Health Check: http://localhost:3000/api/v1/health

Complete API Documentation: Available at http://localhost:3000/api/docs (Swagger UI)

Environment variables (.env):

NODE_ENV=development
PORT=3000
API_VERSION=v1

# Neo4j Configuration
NEO4J_URI=neo4j://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your-password

# App Configuration
CORS_ORIGIN=*
RATE_LIMIT_TTL=60
RATE_LIMIT_MAX=100

# Logging
LOG_LEVEL=debug

open-budget-api/
├── src/
│   ├── config/                    # Configuration files
│   ├── database/
│   │   └── neo4j/                # Neo4j database module
│   ├── modules/
│   │   ├── budget/               # Budget summary & analytics endpoints
│   │   ├── departments/          # Department endpoints & hierarchies
│   │   ├── regions/              # Regional allocation endpoints
│   │   ├── expense-categories/   # Expense classification endpoints
│   │   ├── funding-sources/      # Funding source endpoints
│   │   ├── organizations/        # Organization search & details
│   │   ├── locations/            # Geographic location endpoints
│   │   └── health/               # Health check endpoints
│   ├── common/                   # Shared utilities
│   │   ├── dto/                  # Data Transfer Objects
│   │   ├── filters/              # Exception filters
│   │   └── interceptors/         # Request/Response interceptors
│   ├── app.module.ts             # Root application module
│   └── main.ts                   # Application entry point
├── FRONTEND_INTEGRATION.md       # Frontend integration guide
├── FRONTEND_IMPLEMENTATION_GUIDE.md  # Complete implementation guide
└── README.md                      # This file

# Unit tests
yarn test

# E2E tests
yarn test:e2e

# Test coverage
yarn test:cov

curl "http://localhost:3000/api/v1/budget/summary?year=2025"

Returns comprehensive budget overview with selected year, previous year, and next year comparisons including NEP/GAA totals, growth rates, and statistics.

curl "http://localhost:3000/api/v1/budget/total?year=2025&type=GAA"

curl "http://localhost:3000/api/v1/budget/by-department?year=2025&type=NEP&limit=10"

curl "http://localhost:3000/api/v1/budget/by-department-all?year=2025&includeNepGaa=true"

# Basic department info
curl "http://localhost:3000/api/v1/departments/07"

# With full budget breakdown (agencies, operating unit classes, expense classifications, projects)
curl "http://localhost:3000/api/v1/departments/07?year=2025"

# Basic classification list
curl "http://localhost:3000/api/v1/expense-categories"

# Full hierarchy with NEP/GAA budgets (Classification → SubClass → Group → Object)
curl "http://localhost:3000/api/v1/expense-categories?year=2025"

curl "http://localhost:3000/api/v1/budget/records-mapped?year=2025&type=GAA&page=1&limit=50"

• ✅ Helmet.js security headers
• ✅ CORS configuration
• ✅ Rate limiting (100 requests/minute)
• ✅ Input validation
• ✅ Request compression

• Framework: NestJS
• Database: Neo4j
• Language: TypeScript
• Documentation: Swagger/OpenAPI
• Security: Helmet, Rate Limiting
• Validation: class-validator

This API serves budget data processed and published through the BetterGovPH Open Budget Data repository. The data originates from the Philippine Department of Budget and Management (DBM) and has been structured into a Neo4j graph database for comprehensive analysis.

• Budget Types: NEP (National Expenditure Program) and GAA (General Appropriations Act)
• Fiscal Years: 2020-2026
• Total Records: 6.8+ million budget records
• Total Budget: ₱106.9 trillion across all years
• Dimensions: Full UACS (Unified Accounts Code Structure) hierarchy

The open-budget-data repository contains:

• Raw budget data files (NEP/GAA CSV files)
• Neo4j import scripts for graph database creation
• UACS dimension mappings (departments, agencies, expense classifications, etc.)
• Data validation and processing tools

To use this API, you need to first populate your Neo4j database with the budget data:

1. Clone the open-budget-data repository
2. Follow the setup instructions to import data into Neo4j
3. Configure this API to connect to your populated Neo4j instance

See the open-budget-data README for detailed setup instructions.

This project is part of a larger initiative to create Open APIs for all Philippine government datasets.

For the complete development roadmap, future Open API projects, and our vision for government data transparency, see PLAN.md.

✅ Open Budget API: comprehensive endpoints for budget data analysis

Learn More: See PLAN.md for detailed timelines, planned features, and how to get involved.

MIT License - This project is open source and freely available for use, modification, and distribution.

Contributions are welcome and encouraged! This is an open government data project that benefits from community involvement.

Quick Start:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

For detailed contribution guidelines, development workflow, code style, and testing requirements, please see CONTRIBUTING.md.

Areas for Contribution:

• API endpoint enhancements
• Performance optimizations
• Documentation improvements
• Test coverage
• Bug fixes
• Frontend integration examples
• Data quality validation

• Project: BetterGovPH - Open Government Data Initiative
• API Version: 1.0.0
• Data Repository: open-budget-data
• API Repository: open-budget-api
• Issues: Report bugs or request features via GitHub Issues

• open-budget-data: Source data and Neo4j import scripts
• PLAN.md: Complete roadmap and vision for Open APIs across all government datasets
• CONTRIBUTING.md: Contribution guidelines, development workflow, and code standards
• CODE_OF_CONDUCT.md: Community standards and behavior expectations

Built with ❤️ for Philippine Government Budget Transparency