Documentazione API

Integra IntornoaMe nelle tue applicazioni con le nostre API REST potenti e facili da usare.

📍 Panoramica del Progetto

IntornoaMe è un'applicazione web che utilizza le API di Google Maps per trovare luoghi di interesse vicino alla posizione dell'utente. Il progetto è stato sviluppato con un'architettura moderna che separa il frontend dal backend tramite API REST.

🏗️ Architettura del Progetto

Il progetto è strutturato seguendo le best practice per lo sviluppo web moderno:

🎨

Frontend Reattivo

Interfaccia utente moderna realizzata con HTML5, CSS3 e JavaScript vanilla. Design responsive con animazioni fluide e supporto per dispositivi mobili.

⚡

Backend PHP

API REST sviluppate in PHP 7.4+ che gestiscono le richieste al servizio Google Maps e processano i dati per il frontend.

🔐

Sicurezza

Sistema di autenticazione basato su token di sessione per proteggere le chiamate API e prevenire abusi del servizio.

🔧 Stack Tecnologico

Frontend: HTML5, CSS3 (con CSS Custom Properties), JavaScript ES6+
Backend: PHP 7.4+
API Esterne: Google Maps Places API, Google Maps Geocoding API
Sicurezza: Token di sessione, CORS headers, validazione input
Design Pattern: RESTful API, Responsive Design, Progressive Enhancement

📍 API Endpoints

POST /api/get-places.php

Ricerca luoghi vicini alla posizione specificata utilizzando Google Places API.

Parametri richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`lat`	float	Sì	Latitudine della posizione di ricerca (-90 a 90)
`lng`	float	Sì	Longitudine della posizione di ricerca (-180 a 180)
`radius`	integer	No	Raggio di ricerca in metri (default: 2000, max: 5000)
`type`	string	No	Tipo di luogo da cercare (es: restaurant, cafe, pharmacy)
`keyword`	string	No	Parola chiave per affinare la ricerca

Headers richiesti

Content-Type: application/json
X-API-Token: {session_token}

Esempio richiesta

{
    "lat": 45.4642,
    "lng": 9.1900,
    "radius": 1500,
    "type": "restaurant",
    "keyword": "pizza"
}

Esempio risposta

{
    "success": true,
    "user_location": {
        "lat": 45.4642,
        "lng": 9.1900
    },
    "search_radius": 1500,
    "search_type": "restaurant",
    "results_count": 12,
    "places": [
        {
            "place_id": "ChIJrTLr-GyuEmsRBfy61i59si0",
            "name": "Pizzeria Da Michele",
            "address": "Via Cesare Sersale, 1, Milano",
            "rating": 4.5,
            "user_ratings_total": 324,
            "price_level": 2,
            "types": ["restaurant", "food", "establishment"],
            "icon": "🍽️",
            "location": {
                "lat": 45.4654,
                "lng": 9.1891
            },
            "distance": 156,
            "distance_text": "156 m",
            "is_open": true,
            "business_status": "OPERATIONAL",
            "photo_url": "https://maps.googleapis.com/maps/api/place/photo?...",
            "photo_thumb": "https://maps.googleapis.com/maps/api/place/photo?..."
        }
    ],
    "google_status": "OK",
    "attribution": "Powered by Google Maps"
}

POST /api/get-place-details.php

Ottiene informazioni dettagliate su un luogo specifico tramite il suo place_id.

Parametri richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`place_id`	string	Sì	ID univoco del luogo fornito da Google
`user_lat`	float	No	Latitudine utente per calcolare la distanza
`user_lng`	float	No	Longitudine utente per calcolare la distanza

Esempio risposta

{
    "success": true,
    "details": {
        "place_id": "ChIJrTLr-GyuEmsRBfy61i59si0",
        "name": "Pizzeria Da Michele",
        "formatted_address": "Via Cesare Sersale, 1, 20139 Milano MI, Italia",
        "phone": {
            "formatted": "02 1234 5678",
            "international": "+39 02 1234 5678"
        },
        "website": "https://www.pizzeriadamichele.it",
        "google_maps_url": "https://maps.google.com/?cid=...",
        "rating": 4.5,
        "user_ratings_total": 324,
        "price_level": 2,
        "types": ["restaurant", "food", "establishment"],
        "business_status": "OPERATIONAL",
        "location": {
            "lat": 45.4654,
            "lng": 9.1891
        },
        "opening_hours": {
            "open_now": true,
            "weekday_text": [
                "Lunedì: 12:00–15:00, 19:00–23:00",
                "Martedì: 12:00–15:00, 19:00–23:00",
                ...
            ],
            "periods": [...]
        },
        "photos": [
            {
                "thumb": "https://maps.googleapis.com/maps/api/place/photo?maxwidth=400...",
                "large": "https://maps.googleapis.com/maps/api/place/photo?maxwidth=1200...",
                "attributions": []
            }
        ],
        "reviews": [
            {
                "author_name": "Mario Rossi",
                "rating": 5,
                "relative_time_description": "2 settimane fa",
                "text": "Pizza eccellente, personale cordiale...",
                "time": 1679856000,
                "profile_photo_url": "https://lh3.googleusercontent.com/..."
            }
        ],
        "distance": 156,
        "distance_text": "156 m"
    }
}

🔒 Sicurezza e Autenticazione

Le API utilizzano un sistema di autenticazione basato su token di sessione PHP per garantire che solo gli utenti autorizzati possano accedere ai servizi:

Token generato automaticamente all'avvio della sessione
Token richiesto nell'header X-API-Token per ogni richiesta
Validazione CORS per prevenire richieste cross-origin non autorizzate
Sanitizzazione e validazione di tutti i parametri in input
Rate limiting basato su sessione per prevenire abusi

🚀 Ottimizzazioni Implementate

⚡

Cache dei Risultati

I risultati delle ricerche vengono memorizzati temporaneamente per ridurre le chiamate all'API di Google.

📊

Elaborazione Dati

I dati vengono processati lato server per fornire informazioni ottimizzate e localizzate in italiano.

🎯

Filtri Intelligenti

Sistema di filtraggio avanzato per tipo di luogo, distanza e stato di apertura.

⚠️ Gestione Errori

Le API implementano una gestione robusta degli errori con messaggi descrittivi:

// Errore 400 - Bad Request
{
    "success": false,
    "error": "Coordinate mancanti",
    "received": {...}
}

// Errore 401 - Unauthorized
{
    "success": false,
    "error": "Token non valido"
}

// Errore 500 - Server Error
{
    "success": false,
    "error": "Errore interno del server",
    "message": "Dettagli dell'errore..."
}

📱 Integrazione Frontend

Esempio di chiamata alle API dal frontend JavaScript:

// Funzione per cercare luoghi vicini
async function searchPlaces(lat, lng, type = '', radius = 2000) {
    const response = await fetch('/api/get-places.php', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Token': apiToken
        },
        body: JSON.stringify({
            lat: lat,
            lng: lng,
            radius: radius,
            type: type
        })
    });
    
    if (!response.ok) {
        throw new Error('Errore nella ricerca');
    }
    
    const data = await response.json();
    return data;
}

// Utilizzo
navigator.geolocation.getCurrentPosition(async (position) => {
    const results = await searchPlaces(
        position.coords.latitude,
        position.coords.longitude,
        'restaurant'
    );
    
    console.log(`Trovati ${results.results_count} ristoranti`);
    results.places.forEach(place => {
        console.log(`${place.name} - ${place.distance_text}`);
    });
});

Vuoi integrare IntornoaMe?

Le nostre API sono disponibili per sviluppatori che vogliono integrare la ricerca di luoghi nelle proprie applicazioni.

Contattaci per le API