Documentazione API

Integra Maphira nelle tue applicazioni con la nostra API REST

Indice
Autenticazione API v1 - Lista scansioni API v1 - Nuova scansione API v1 - Risultati API v1 - Elimina
Sitemap - Scopri Sitemap - Estrai URL Site URLs
Autenticazione API

Per utilizzare le API di Maphira, devi autenticarti con una chiave API. Puoi creare le tue chiavi dalla pagina Chiavi API.

Ottenere una chiave API
  1. Accedi al tuo account Maphira
  2. Vai su Menu utente → Chiavi API
  3. Clicca su Genera chiave
  4. Copia e conserva la chiave in modo sicuro
Usare la chiave API

Includi la chiave nell'header Authorization di ogni richiesta:

Authorization: Bearer maphira_xxxxxxxxxxxxxx
Esempio con cURL
curl -X GET "https://maphira.com/api/v1/scans" \
  -H "Authorization: Bearer maphira_tua_chiave_api"
Nota: Le chiavi API hanno accesso solo alle scansioni del tuo account. Non condividere mai le tue chiavi.
GET Lista scansioni
/api/v1/scans

Restituisce tutte le scansioni del tuo account.

Esempio
curl -X GET "https://maphira.com/api/v1/scans" \
  -H "Authorization: Bearer maphira_xxx"
Response
{
  "scans": [
    {
      "id": "abc123-def456",
      "url": "https://example.com",
      "status": "completed",
      "max_pages": 50,
      "pages_found": 25,
      "created_at": "2026-02-03T10:30:00",
      "scan_time_seconds": 45.2
    }
  ],
  "total": 1
}
POST Nuova scansione
/api/v1/scan

Avvia una nuova scansione associata al tuo account.

Request Body
{
  "url": "https://example.com",
  "xpaths": [
    ["Titolo", "//title/text()"],
    ["H1", "//h1/text()"]
  ],
  "max_pages": 50,
  "timeout": 60,
  "enable_ai": true,
  "light_scan": false,
  "follow_nofollow": false,
  "schedule_enabled": true,
  "schedule_day": 15
}
Parametri
NomeTipoDescrizione
urlstringURL del sito da scansionare (obbligatorio)
xpathsarrayArray di [nome, xpath] per estrazione contenuti
max_pagesintegerNumero massimo di pagine (default: 50, max: 5000)
timeoutintegerTimeout in secondi (default: 60, max: 3600)
enable_aibooleanAbilita analisi AI semiotica e neuromarketing (default: false)
light_scanbooleanScansione leggera con campi essenziali (default: false)
follow_nofollowbooleanSegui anche i link nofollow durante il crawl (default: false). Per default i link nofollow vengono ignorati.
schedule_enabledbooleanAbilita scansione mensile automatica (default: false)
schedule_dayintegerGiorno del mese per scansione automatica (1-28, default: 1)
Analisi AI: Se abilitata, ogni pagina viene analizzata con tecniche di semiotica e neuromarketing. Campi restituiti: ai_entities, ai_framing, ai_priming, ai_wow_effect, ai_hormones, ai_persuasion (principi di Cialdini), ai_intent, ai_funnel, ai_motivations, ai_needs, ai_fears, ai_eee_model, ai_coherence_score, ai_archetype.
Schedulazione: Se schedule_enabled è true, la scansione verrà ripetuta automaticamente ogni mese nel giorno specificato. Lo scheduler verifica ogni ora ed evita ri-esecuzioni entro 25 giorni.
Esempio
curl -X POST "https://maphira.com/api/v1/scan" \
  -H "Authorization: Bearer maphira_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "max_pages": 10}'
Response
{
  "job_id": "abc123-def456",
  "status": "starting",
  "message": "Scansione avviata con successo"
}
GET Risultati scansione
/api/v1/scan/{job_id}/results

Ottiene i risultati completi di una scansione, incluse tutte le pagine.

Query Parameters
NomeTipoDescrizione
fieldsstringLista di campi separati da virgola (opzionale). Riduce la risposta ai soli campi richiesti.
Campi disponibili

url, status, robots_indexable, title, meta_desc, h1, depth, word_count, canonical, lang, date_published, date_modified, links_internal_count, redirect_url, ai_intent, ai_funnel, ai_archetype, ai_entities, ai_framing, ai_persuasion, ...

Esempio base
curl -X GET "https://maphira.com/api/v1/scan/abc123/results" \
  -H "Authorization: Bearer maphira_xxx"
Esempio con filtro campi
curl -X GET "https://maphira.com/api/v1/scan/abc123/results?fields=url,title,ai_intent,ai_funnel" \
  -H "Authorization: Bearer maphira_xxx"
Response
{
  "scan": {
    "id": "abc123",
    "url": "https://example.com",
    "status": "completed",
    "pages_found": 25
  },
  "pages": [
    {
      "url": "https://example.com/page1",
      "title": "Page Title",
      "ai_intent": "informativo",
      "ai_funnel": "awareness"
    }
  ],
  "total_pages": 25,
  "fields_requested": ["url", "title", "ai_intent", "ai_funnel"]
}
DELETE Elimina scansione
/api/v1/scan/{job_id}

Elimina una scansione e tutti i suoi dati.

Esempio
curl -X DELETE "https://maphira.com/api/v1/scan/abc123" \
  -H "Authorization: Bearer maphira_xxx"
Response
{
  "message": "Scansione eliminata con successo"
}
POST Ripeti scansione (Refresh)
/api/v1/scan/{job_id}/refresh

Crea una nuova scansione con gli stessi parametri della scansione originale (URL, XPaths, impostazioni AI, ecc.).

Esempio
curl -X POST "https://maphira.com/api/v1/scan/abc123/refresh" \
  -H "Authorization: Bearer maphira_xxx"
Response
{
  "message": "Scansione refresh avviata",
  "scan": {
    "id": "new-scan-id",
    "url": "https://example.com",
    "status": "pending",
    "parent_scan_id": "abc123"
  },
  "original_scan_id": "abc123"
}
POST Aggiungi URL a scansione esistente
/api/v1/scan/{job_id}/add-urls

Aggiunge URL specifiche a una scansione esistente. Usa le stesse impostazioni della scansione originale (XPath, AI, scansione leggera). Non esegue crawling - scansiona solo gli URL specificati, ideale per risparmiare costi API.

Request Body
{
  "urls": [
    "https://example.com/nuova-pagina-1/",
    "https://example.com/nuova-pagina-2/",
    "https://example.com/blog/articolo/"
  ]
}
Parametri
NomeTipoDescrizione
urlsarrayArray di URL da aggiungere alla scansione (obbligatorio)
Esempio
curl -X POST "https://maphira.com/api/v1/scan/abc123/add-urls" \
  -H "Authorization: Bearer maphira_xxx" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com/pagina1/", "https://example.com/pagina2/"]}'
Response
{
  "message": "Aggiunta URL avviata",
  "scan": {
    "id": "abc123",
    "status": "running"
  },
  "urls_to_add": 2,
  "urls_skipped": 0,
  "existing_pages": 50
}

Nota: Gli URL duplicati o già presenti nella scansione vengono ignorati automaticamente. Gli URL vengono normalizzati con trailing slash.

POST Riprendi scansione bloccata
/api/v1/scan/{job_id}/resume

Riprende una scansione che si è bloccata o è fallita, continuando dal punto in cui si era fermata. Ideale per scansioni interrotte a metà.

Status ammessi
StatusDescrizione
blockedScansione bloccata dopo aver salvato alcune pagine
failedScansione fallita (riparte da eventuali pagine esistenti)
Esempio
curl -X POST "https://maphira.com/api/v1/scan/abc123/resume" \
  -H "Authorization: Bearer maphira_xxx"
Response
{
  "message": "Scansione ripresa",
  "scan": {
    "id": "abc123",
    "status": "running"
  },
  "pages_already_done": 25,
  "max_pages": 100,
  "remaining": 75
}

Nota: La scansione riprende con le stesse impostazioni originali (XPath, AI, scansione leggera). Gli URL già scansionati vengono saltati automaticamente.

PATCH Aggiorna schedulazione
/api/v1/scan/{job_id}/schedule

Aggiorna le impostazioni di schedulazione mensile per una scansione esistente.

Request Body
{
  "schedule_enabled": true,
  "schedule_day": 15
}
Parametri
NomeTipoDescrizione
schedule_enabledbooleanAbilita/disabilita la scansione mensile automatica
schedule_dayintegerGiorno del mese (1-28) in cui eseguire la scansione
Esempio
curl -X PATCH "https://maphira.com/api/v1/scan/abc123/schedule" \
  -H "Authorization: Bearer maphira_xxx" \
  -H "Content-Type: application/json" \
  -d '{"schedule_enabled": true, "schedule_day": 15}'
Response
{
  "message": "Schedulazione aggiornata",
  "scan": {
    "id": "abc123",
    "schedule_enabled": true,
    "schedule_day": 15
  }
}

Sitemap Extractor

Scopri e analizza le sitemap di qualsiasi sito web, poi estrai tutti gli URL con metadati. Flusso in due fasi: prima scopri le sitemap disponibili, poi estrai gli URL da quelle selezionate.

POST Scopri sitemap
/api/v1/sitemap/discover

Analizza un dominio per trovare tutte le sitemap disponibili. Cerca nel robots.txt, nei percorsi CMS comuni (WordPress, Yoast, ecc.) e supporta sitemap index con nidificazione.

Request Body
{
  "domain": "example.com"
}
Parametri
NomeTipoDescrizione
domainstringDominio da analizzare (obbligatorio, es. "example.com")
Esempio
curl -X POST "https://maphira.com/api/v1/sitemap/discover" \
  -H "Authorization: Bearer maphira_xxx" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'
Response
{
  "domain": "example.com",
  "total_sitemaps": 4,
  "total_urls": 146,
  "discovered_sitemaps": [
    {
      "url": "https://example.com/sitemap_index.xml",
      "type": "index",
      "accessible": true,
      "url_count": 146,
      "lastmod": null,
      "child_sitemaps": [
        {
          "url": "https://example.com/post-sitemap.xml",
          "type": "urlset",
          "accessible": true,
          "url_count": 120,
          "lastmod": "2026-02-04T19:17:47+00:00"
        },
        {
          "url": "https://example.com/page-sitemap.xml",
          "type": "urlset",
          "accessible": true,
          "url_count": 25,
          "lastmod": null
        }
      ]
    }
  ]
}
Tipo sitemap: index = sitemap indice che contiene riferimenti ad altre sitemap. urlset = sitemap che contiene URL finali. Per estrarre tutti gli URL da un indice, puoi passare direttamente l'URL dell'indice all'endpoint di estrazione.
POST Estrai URL da sitemap
/api/v1/sitemap/extract

Estrae tutti gli URL dalle sitemap selezionate, con metadati come data di modifica, frequenza di aggiornamento e priorità. Supporta sia sitemap singole che sitemap indice (estrae ricorsivamente da tutte le figlie).

Request Body
{
  "sitemap_urls": [
    "https://example.com/sitemap_index.xml"
  ]
}
Parametri
NomeTipoDescrizione
sitemap_urlsarrayArray di URL di sitemap da cui estrarre (obbligatorio). Puoi passare URL di sitemap indice o sitemap singole.
Esempio - Estrai da indice (tutte le figlie)
curl -X POST "https://maphira.com/api/v1/sitemap/extract" \
  -H "Authorization: Bearer maphira_xxx" \
  -H "Content-Type: application/json" \
  -d '{"sitemap_urls": ["https://example.com/sitemap_index.xml"]}'
Esempio - Estrai da sitemap specifiche
curl -X POST "https://maphira.com/api/v1/sitemap/extract" \
  -H "Authorization: Bearer maphira_xxx" \
  -H "Content-Type: application/json" \
  -d '{"sitemap_urls": ["https://example.com/post-sitemap.xml", "https://example.com/page-sitemap.xml"]}'
Response
{
  "total_urls": 146,
  "urls": [
    {
      "url": "https://example.com/blog/articolo-1/",
      "lastmod": "2026-02-04T19:17:47+00:00",
      "changefreq": null,
      "priority": null,
      "source_sitemap": "https://example.com/post-sitemap.xml"
    },
    {
      "url": "https://example.com/chi-siamo/",
      "lastmod": "2026-01-15T10:30:00+00:00",
      "changefreq": "monthly",
      "priority": "0.8",
      "source_sitemap": "https://example.com/page-sitemap.xml"
    }
  ]
}
Flusso consigliato: Usa prima /api/v1/sitemap/discover per trovare le sitemap, poi passa gli URL desiderati a questo endpoint. Se vuoi tutti gli URL, passa direttamente l'URL della sitemap indice.
POST Aggiungi URL a scansione esistente
/api/v1/add-urls

Aggiunge URL specifiche all'ultima scansione completata del dominio. Maphira riconosce automaticamente il dominio dalla prima URL e trova la scansione giusta. L'elaborazione avviene in background: la risposta è immediata. L'analisi AI viene applicata automaticamente se la scansione originale era stata creata con AI attiva.

Request Body
{
  "urls": [
    "https://www.esempio.it/pagina-nuova",
    "https://www.esempio.it/altra-pagina"
  ]
}
Parametri
NomeTipoDescrizione
urlsarrayLista di URL da aggiungere (obbligatorio, max 50). Il dominio viene riconosciuto automaticamente dalla prima URL.
Esempio
curl -X POST "https://maphira.com/api/v1/add-urls" \
  -H "Authorization: Bearer maphira_xxx" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://www.esempio.it/nuova-pagina"]}'
Response
{
  "status": "success",
  "message": "1 URL in fase di elaborazione"
}
Note: La scansione viene trovata automaticamente dal dominio. L'elaborazione avviene in background. Le URL già presenti vengono ignorate. L'analisi AI viene applicata automaticamente in base alle impostazioni della scansione originale.
POST Site URLs - Mappa completa del sito
/api/v1/site-urls

Analizza un sito web tramite le sue sitemap e restituisce tutte le URL con titolo, sezione e categoria. Ideale per ottenere una mappa strutturata del sito in un'unica chiamata.

Request Body
{
  "site_url": "https://www.esempio.it",
  "max_urls": 500,
  "fetch_titles": true
}
Parametri
NomeTipoDescrizione
site_urlstringURL completo del sito da analizzare (obbligatorio)
max_urlsintegerNumero massimo di URL da restituire (default: 500, max: 5000)
fetch_titlesbooleanSe recuperare i titoli delle pagine (default: true). Impostare a false per risposte più veloci.
Esempio
curl -X POST "https://maphira.com/api/v1/site-urls" \
  -H "Authorization: Bearer maphira_xxx" \
  -H "Content-Type: application/json" \
  -d '{"site_url": "https://www.esempio.it"}'
Response
{
  "site_url": "https://www.esempio.it",
  "total_urls": 3,
  "sitemaps_found": 2,
  "urls": [
    {
      "url": "https://www.esempio.it/blog/guida-seo-2025",
      "title": "Guida SEO 2025: Tutto Quello che Devi Sapere",
      "section": "blog",
      "category": "Guida Seo 2025",
      "lastmod": "2026-01-15T10:30:00+00:00"
    },
    {
      "url": "https://www.esempio.it/servizi/web-design",
      "title": "Servizi di Web Design",
      "section": "servizi",
      "category": "Web Design",
      "lastmod": null
    },
    {
      "url": "https://www.esempio.it/",
      "title": "Home - Esempio",
      "section": "home",
      "category": null,
      "lastmod": "2026-02-01T08:00:00+00:00"
    }
  ]
}
Come funziona: L'endpoint scopre automaticamente le sitemap del sito, estrae tutte le URL, e per ciascuna recupera il titolo della pagina (in parallelo per velocità). La section viene derivata dal primo segmento del path URL. La category viene derivata dal secondo segmento per sezioni come blog, news, prodotti, ecc.