VIEWS Simple API is a REST API that offers public access to the data from the VIEWS conflict forecasting system.
Using the raw prediction data from VIEWS and the views_pipeline_core module for statystical analasys it simplifies the process of handling the data and directly gives the user the information they need.
Created for the VIEWS Challenge: Turning Conflict Forecasts into Accessible APIs during the Junction x Oulu Hackaton 2025
- Searchable by Country, Grid IDs and Range of Months
- Precise selection of metrics returning only relevant information
- Optimization for large amounts of data using compression, caching and pagination
- Simple Access-Key system for access rights and rate-limiting
- Fully Conteinerized and easy deployment
- Highly customizable
- Database for storing pre-computed data from multiple sources
- Endpoints for returning interactive graphs
- More statistics
VIEWS Simple API is built with a modern Python stack, designed for performance, maintainability, and easy deployment. The codebase emphasizes clean, testable, and efficient practices, making it simple to extend and customize for different use cases.
- Python – Core language for API logic and data processing
- FastAPI – High-performance REST API framework
- Pytest – Framework for automated testing
- Ruff – Linter for consistent code quality
- Makefile – Automates common development tasks
- Docker – Containerization for consistent deployment
This porject required Python3.11 to run. Follow these steps to get it running on your system.
- Set up a Python 3.11 virtual environment
python3.11 -m venv venv
source venv/bin/activate # Linux/Mac
venv\Scripts\activate # Windows- Install dependencies
make install-
Import data
Add
preds_001.parquetin/env -
Run the API locally
make run-
Build the Docker image
sudo docker build -t views_challenge:latest . -
Run the Docker container
sudo docker run -p 8000:8000 views_challenge:latest
-
Check code linting using ruff
make lint
-
Run automated tests using pytest
make test
The API requires environment variables to run properly. A sample configuration file is provided in the repository.
-
Copy the example file
cp .env.example .env
-
Update the
.envfile with your own settings
The application will automatically load variables from the .env file when starting up.
❗ In order to use api-keys you need to have key_mode set to true and have valid database credentials
FastAPI provides dynamicly updated /docs endpoint that helps with basic documentation and testing of endpoints
- /months - returns an id list of all available months
- /countries - returns an id list for all available countries
- /all_cells - returns a id list of all available grid cells
- /cells - accepts cells identifiers from the user (e.g. cell id, country id), filters the dataset based on them, returns calculated values requested by the user (e.g. MAP (mean value), 3 confidence intervals (50%, 90%, 99%), and 6 probabilities of passing certain thresholds (plus a few helper values like grid ID, location, country ID))
- GET /cells?return_params=map_value,ci_90,ci_99 - return MAP estimates and 90/99% confidence intervals for all cells (limit may apply)
- GET /cells?country_id=45&violence_types=sb,ns&return_params=map_value,prob_above_050 - return MAP and probability of violence exceeding 0.5 for cells with country id equal to 49
- /create_user_api_key - Generates a standart api key and saves it to the database
- /create_admin_api_key - Generates an admin api key and saves it to the database, requires admin key to be accessed
- /get_key_info/{key} - Fetches information about the provided api key from the database
- /revoke_key/{key} - Revokes provided api key, requires admin key to be accessed