REST API for OSM Notes Analytics and Ingestion. Unified programmatic access to user profiles, country analytics, advanced search capabilities, rankings, comparisons, and real-time metrics. Extends OSM API 0.6 with specialized analytics features.
OSM Notes API provides programmatic access to OpenStreetMap notes analytics data, including:
- User Profiles: Detailed statistics of contributors
- Country Analytics: Aggregated metrics by country
- Advanced Search: Complex filters and dynamic queries
- Rankings: User and country classifications
- Comparisons: Comparative analysis between entities
- Trends: Temporal data analysis
- Notes and Comments: Access to OSM notes and their comments
This API is COMPLEMENTARY to the static JSON system, NOT a replacement.
- ✅ JSON system maintained: The Viewer and other consumers continue using static JSON files
- ✅ API is additional: For use cases requiring dynamic queries or integrations
- ✅ Both coexist: Each system is used according to the specific use case
- Node.js >= 18.0.0
- npm >= 9.0.0
- PostgreSQL 15+ (with access to
osm_notes_dwh) - Redis 7+ (optional but recommended)
# Clone repository
git clone https://github.com/osmlatam/OSM-Notes-API.git
cd OSM-Notes-API
# Install dependencies
npm install
# Configure environment variables
cp .env.example .env
# Edit .env with your configurations
# Build TypeScript
npm run build
# Start application
npm start# Start services
docker-compose -f docker/docker-compose.yml up -d
# View logs
docker-compose -f docker/docker-compose.yml logs -f apiSee docs/INSTALLATION.md for detailed instructions.
- Installation - Complete installation guide
- Usage - API usage manual
- API Reference - OpenAPI/Swagger documentation
- Contributing - Contributor guide
- Changelog - Change history
OSM-Notes-API/
├── src/ # Source code
│ ├── config/ # Configuration
│ ├── routes/ # API routes
│ ├── controllers/ # Controllers
│ ├── services/ # Business logic
│ ├── middleware/ # Custom middleware
│ ├── utils/ # Utilities
│ └── types/ # TypeScript types
├── tests/ # Tests
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── load/ # Load tests
├── docs/ # Documentation
│ ├── INSTALLATION.md # Installation manual
│ ├── USAGE.md # Usage manual
│ └── api/ # OpenAPI documentation
├── docker/ # Docker configuration
└── package.json # Dependencies and scripts
npm run build # Build TypeScript
npm start # Run compiled application
npm run dev # Development with hot reload
npm test # Run tests
npm run test:unit # Unit tests only
npm run test:coverage # Tests with coverage
npm run lint # Run ESLint
npm run format # Format code with Prettier
npm run type-check # Verify TypeScript types- User-Agent required: All requests must include a valid User-Agent with format
AppName/Version (Contact) - Rate Limiting: 50 requests/15min for anonymous users
- Anti-abuse protection: Automatic blocking of known AIs and bots
- Optional OAuth: Available for advanced features (Phase 5)
See docs/USAGE.md for more security details.
Version: 0.1.0 (MVP in development)
Implementation Phases:
- ✅ Phase 1: MVP (in progress)
- ⏳ Phase 2: Basic Features
- ⏳ Phase 3: Advanced Features
- ⏳ Phase 4: Production
- ⏳ Phase 5: Webhooks and Notifications
Contributions are welcome. Please read CONTRIBUTING.md for details on our code of conduct and pull request process.
This project is licensed under the MIT License - see LICENSE for details.
For questions or support, please open an issue on GitHub.
Note: This project is part of the OSM Notes ecosystem and is designed to work together with the other projects in the ecosystem.