MIUR/MIM Open-Data REST API

An unofficial REST API for the MIUR/MIM Open-Data. Using FastAPI and SPARQL.

Report Bug · Request Feature

All the data used in this project is owned by the respective owners and is used for educational purposes only. The data is taken from the official MIUR/MIM Open-Data website.

Features

• Get and query all the data about the schools in Italy
• Cache the data to reduce the number of requests to the MIUR/MIM Open-Data website

API Endpoints

Tip

The API is self-documented. You can access the Swagger UI at /docs and the ReDoc UI at /redoc.

Base URL

  https://miur-api.cloud.matteosillitti.it/v1/

Schools

• /schools - Get all the schools or filter them by SchoolBase model.

Query parameters

• limit - Limit the number of results (default: 50, max: 1500)
• exclude_par - Exclude private schools (default: false)
• exclude_aut - Exclude autonomous schools like Aosta, Trento e Bolzano (default: false)

Body (SchoolBase model)

{
  "school_year": 202425,
  "geographic_area": "string",
  "region": "string",
  "province": "string",
  "school_code": "string",
  "school_name": "string",
  "school_address": "string",
  "school_postal_code": "string",
  "school_city_code": "string",
  "city_description": "string",
  "education_type_description": "string",
  "school_email_address": "string",
  "school_certified_email_address": "string",
  "school_website": "string",
}

Response

{
    "details": {
        "schools": [
            {
                "school_year": 202425,
                "geographic_area": "ISOLE",
                "region": "SICILIA",
                "province": "CALTANISSETTA",
                "school_code": "CLTD090005",
                "school_name": "\"M. RAPISARDI\" - CALTANISSETT",
                "school_address": "VIALE REGINA MARGHERITA",
                "school_postal_code": "93100",
                "school_city_code": "B429",
                "city_description": "CALTANISSETTA",
                "education_type_description": "ISTITUTO TECNICO COMMERCIALE",
                "school_email_address": "[email protected]",
                "school_certified_email_address": "Non Disponibile",
                "school_website": ""
            }
        ],
        "total": 
    },
    "success": true,
    "status_code": 200
}

Cache

The API uses a cache system to reduce the number of requests to the MIUR/MIM Open-Data website. The cache expiration time is set to 1 hour by default. You can change it using the CACHE_EXPIRE environment variable. The cache is stored in memory and is not persistent. Soon I will add the possibility to use Redis as a cache.

Public instance of the API

An instance of the API is available at https://miur-api.cloud.matteosillitti.it/

Limited to 20 requests per day (2 requests per minute). If you need more requests, contact me.

Environment Variables

Variable	Description	Default
PUID	User ID (docker)	1000
PGID	Group ID (docker)	1000
DOMAIN	Domain of the API	localhost
PORT	Port of the API	5000
CACHE_EXPIRE	Cache expiration time in seconds	3600 (1 hour)

Installation - Using Docker Compose (recommended)

Clone the project

version: '3'

services:
  miur_opendata_rest_api:
    image: matt0550/miur-opendata-rest-api
    environment:
      - PUID=1000
      - PGID=1000
    ports:
      - 5000:5000
    restart: unless-stopped

Run the container with docker-compose up -d

Installation - Using Docker Run

Pull the image

  docker run -d -p 5000:5000 -e PUID=1000 -e PGID=1000 matt0550/miur-opendata-rest-api

Installation - Self-Host or docker build

Clone the project

  git clone https://github.com/Matt0550/MIUR-OpenData-rest-api

Go to the project directory

  cd MIUR-OpenData-rest-api-master

OPTIONAL: use docker to build the image

  docker build -t MIUR-OpenData-rest-api .

If you don't want to use docker, skip this step. Else, change the image in docker-compose.yml with the image name you used. Run the container with docker-compose up -d

Install dependencies

  poetry install

Start the REST API (after setting the environment variables)

  cd app
  uvicorn main:app

Help - feedback

You can contact me on:

Discord: https://go.matteosillitti.it/discord

Telegram: https://go.matteosillitti.it/telegram

Mail: [email protected]

License

GNU GPLv3

Support me