Events API

How to make an API call

API call

Parameters

Example of API call

If you want to filter events by date and city only:

If you want to filter by all three parameters:

If you do not need to filter and want to retrieve all events:

Example of API response

To view the API response, expand the example by clicking the triangle.

{
  "events": [
    {
      "id": 123,
      "name": "Concerto di Estate",
      "description": "Una serata di musica dal vivo con artisti emergenti...",
      "category": "Musica",
      "startDateTime": "2024-08-10T20:00:00",
      "endDateTime": "2024-08-10T23:30:00",
      "issueDateTime": "2024-07-01T10:00:00",
      "media": [
        {
          "id": 45,
          "name": "locandina.jpg",
          "type": "image/jpeg",
          "url": "https://cdn.esercitazioni.online/media/locandina.jpg"
        }
      ],
      "venue": {
        "id": 78,
        "name": "Arena Comunale",
        "address": {
          "street": "Via Roma 10",
          "city": "Milano",
          "province": "MI"
        }
      },
      "contact": {
        "email": "info@arena.it",
        "phone": "+39 02 1234567"
      }
    }
  ]
}

Fields in API response

• events — Array of event objects matching the applied filters
• events[].id — Integer. Unique event identifier
• events[].name — String. Event title
• events[].description — String or null. Event description text
• events[].category — String or null. Category/ambito name
• events[].startDateTime — String (ISO 8601). Event start: YYYY-MM-DDTHH:mm:ss
• events[].endDateTime — String (ISO 8601). Event end: YYYY-MM-DDTHH:mm:ss
• events[].issueDateTime — String (ISO 8601). Publication time: YYYY-MM-DDTHH:mm:ss
• events[].media — Array. List of multimedia assets
  • media[].id — Integer. Unique media identifier
  • media[].name — String. Original filename
  • media[].type — String. MIME type (e.g. image/jpeg)
  • media[].url — String. Public URL to access the file
• events[].venue — Object. Venue information
  • venue.id — Integer or null. Unique venue identifier
  • venue.name — String or null. Venue name
  • venue.address — Object. Address details
    • address.street — String or null
    • address.city — String or null
    • address.province — String or null (e.g. MI, RM)
• events[].contact — Object. Contact for inquiries
  • contact.email — String or null
  • contact.phone — String or null

HTTP Methods & Status Codes

Supported methods

Status Codes

Example of error responses

Invalid date format

GET /api/?date=25-12-2024

{
  "error": "Invalid date format. Use YYYY-MM-DD"
}

Parameter too long

{
  "error": "Category too long"
}

Unsupported HTTP method

{
  "error": "Method not allowed"
}

CORS & Security Headers

Response headers

Content-Type: application/json; charset=UTF-8
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: no-referrer
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type

Quick Start Examples

cURL

# Tutti gli eventi
curl "https://esercitazioni.online/api/"

# Esempio reale: ricerca evento "Porte aperte all'ITSOS Marie Curie (Open Day)" per data, categoria e città
curl -G "https://esercitazioni.online/api/" \
    --data-urlencode "date=2023-11-25" \
    --data-urlencode "category=open day" \
    --data-urlencode "city=Cernusco sul Naviglio" \
    -H "Accept: application/json"

JavaScript (Fetch API)

const params = new URLSearchParams({
    date: '2023-11-25',
    category: 'open day',
    city: 'Cernusco sul Naviglio'
});

const response = await fetch(
    `https://esercitazioni.online/api/?${params.toString()}`,
    { headers: { 'Accept': 'application/json' } }
);

const data = await response.json();
console.log(data.events);

Python (requests)

import requests

url = "https://esercitazioni.online/api/"
params = {
    "date": "2023-11-25",
    "category": "open day",
    "city": "Cernusco sul Naviglio"
}

response = requests.get(
    url,
    params=params,
    headers={"Accept": "application/json"}
)
data = response.json()

for event in data.get("events", []):
    print(f"{event['name']} - {event['venue']['address']['city']}")

Technical Notes & FAQ

FAQ

• Q: Is authentication required?
  A: No. The API is publicly accessible. Rate limiting and authentication can be added on request.
• Q: Can I filter by date range?
  A: Not currently. The date parameter accepts a single date and matches events that start OR end on that date. For range filtering, please contact the development team.
• Q: How are events without a category handled?
  A: The category field will be null in the response.
• Q: Is the data real-time?
  A: Yes. The API queries the database directly. Newly published events may take a few seconds to appear depending on database replication or caching layers.