Documentazione API

Documentazione completa dell'API pubblica di Mapfolio - Accedi ai dati delle aziende svizzere in modo programmatico

Interactive API Documentation
Explore all available endpoints, request parameters, response schemas, and try out API calls directly in your browser.
View OpenAPI Documentation

Panoramica

L'API Mapfolio fornisce l'accesso programmatico ai dati delle aziende svizzere tramite un'interfaccia RESTful. Tutti gli endpoint sono documentati utilizzando la specifica OpenAPI 3.0, garantendo coerenza e facilità di integrazione.

Iniziare

Autenticazione

L'API Mapfolio utilizza l'autenticazione tramite chiave API. Puoi ottenere la tua chiave API dalle tue impostazioni dell'account.

Intestazione chiave API:

X-API-Key: mapf_tua_chiave_api_qui

Token Bearer (Alternativa):

Authorization: Bearer mapf_tua_chiave_api_qui

URL di base

Tutte le richieste API devono essere effettuate a:

https://mapfolio.app

Limitazione della velocità

Le richieste API sono limitate per garantire un utilizzo equo:

  • Richieste autenticate: 1000 richieste all'ora per chiave API
  • Richieste non autenticate: 10 richieste all'ora per indirizzo IP

Le informazioni sul limite di velocità sono incluse nelle intestazioni di risposta:

  • X-RateLimit-Limit: Numero massimo di richieste consentite
  • X-RateLimit-Remaining: Richieste rimanenti nella finestra corrente
  • X-RateLimit-Reset: Timestamp Unix quando il limite si resetta

Endpoint disponibili

Ricerca aziende

Cerca aziende con opzioni di filtraggio avanzate:

  • Ricerca testuale nei nomi delle aziende
  • Filtra per cantone (cantoni svizzeri)
  • Filtra per stato dell'azienda
  • Supporto alla paginazione

Dettagli azienda

Recupera informazioni dettagliate su aziende specifiche:

  • Dati del profilo aziendale
  • Informazioni sulla posizione
  • Stato legale
  • Dettagli di registrazione

Statistiche

Accedi a statistiche aggregate sulle aziende svizzere:

  • Conteggi complessivi delle aziende
  • Statistiche a livello di cantone
  • Distribuzioni basate su lettere
  • Conteggi di combinazioni di due lettere

Autocompletamento

Ottieni suggerimenti di autocompletamento per:

  • Nomi di aziende
  • Città
  • Codici postali

Aziende casuali

Recupera campioni casuali di aziende per test ed esplorazione.

Formato della risposta

Tutte le risposte API di successo seguono una struttura coerente:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

Le risposte di errore includono informazioni dettagliate:

{
  "error": "Messaggio di errore",
  "details": "Dettagli aggiuntivi dell'errore"
}

Codici di errore

  • 400 Bad Request: Parametri di richiesta non validi
  • 401 Unauthorized: Chiave API mancante o non valida
  • 403 Forbidden: Permessi insufficienti
  • 404 Not Found: Risorsa non trovata
  • 429 Too Many Requests: Limite di velocità superato
  • 500 Internal Server Error: Errore lato server

Specifica OpenAPI

La specifica OpenAPI 3.0 completa è disponibile su:

Puoi utilizzare la specifica OpenAPI con qualsiasi strumento compatibile:

  • Swagger UI
  • Postman
  • Insomnia
  • Generatori di codice per librerie client

Esempi di codice

cURL

curl -H "X-API-Key: mapf_tua_chiave_api_qui" \
  https://mapfolio.app/api/search?q=tecnologia

JavaScript (Fetch)

const response = await fetch('https://mapfolio.app/api/search?q=tecnologia', {
  headers: {
    'X-API-Key': 'mapf_tua_chiave_api_qui'
  }
})
const data = await response.json()

Python (Requests)

import requests

headers = {'X-API-Key': 'mapf_tua_chiave_api_qui'}
response = requests.get(
  'https://mapfolio.app/api/search',
  params={'q': 'tecnologia'},
  headers=headers
)
data = response.json()

Supporto

Per supporto API e domande:

Termini di utilizzo

Utilizzando l'API Mapfolio, accetti i nostri Termini di servizio e la nostra Informativa sulla privacy. Si prega di rivedere i limiti di velocità e le linee guida di utilizzo per garantire la conformità.