API Italianonprofit
Api Reference

Ricerca Organizzazioni

Ricerca avanzata delle organizzazioni non profit con Elasticsearch v9

L'endpoint di ricerca permette di cercare organizzazioni non profit utilizzando query Elasticsearch v9 completamente personalizzabili.

Endpoint

POST https://nitro.italianonprofit.it/api/v1/organizations/search

Autenticazione

L'endpoint richiede autenticazione tramite:

  • PASETO Token: nell'header Authorization: Bearer <token>
  • API Key: nell'header Authorization: Bearer <api-key> o X-API-Key: <api-key>

Parametri della Richiesta

Body

{
  "index": "organization-serp*",
  "body": {
    "query": {
      "match": {
        "name": "associazione"
      }
    },
    "size": 10,
    "from": 0
  }
}

Campi:

  • index (obbligatorio): Nome dell'indice Elasticsearch. Deve iniziare con:
    • organization-serp* - Per ricerche full-text su organizzazioni
    • organization-entity* - Per ricerche su entità organizzazioni
    • map-serp* - Per ricerche geografiche
  • body (obbligatorio): Body completo della query Elasticsearch che può includere:
    • query: La query Elasticsearch (obbligatoria)
    • size: Numero di risultati da restituire (default: 10)
    • from: Offset per la paginazione (default: 0)
    • sort: Ordinamento risultati
    • aggs: Aggregazioni per analisi dati

Formato della Risposta

Risposta di Successo

{
  "status": "success",
  "data": {
    "results": [
      {
        "id": "123",
        "name": "Associazione Esempio",
        "tax_code": "12345678901",
        "legal_status": "APS",
        ...
      }
    ],
    "total": 42,
    "index": "organization-serp*",
    "version": "v9"
  },
  "meta": {
    "requestId": "uuid-unico",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Campi della risposta:

  • results: Array con i risultati della ricerca
  • total: Numero totale di risultati trovati
  • index: Indice interrogato
  • version: Versione Elasticsearch utilizzata (v9)

Indici Disponibili

organization-serp*

Indice ottimizzato per ricerche full-text su organizzazioni. Ideale per:

  • Ricerca per nome organizzazione
  • Ricerca per descrizione
  • Ricerca fuzzy e partial matching

organization-entity*

Indice con dati strutturati delle organizzazioni. Ideale per:

  • Ricerca per codice fiscale
  • Ricerca per stato legale
  • Filtri su campi specifici

map-serp*

Indice geografico per ricerche basate su posizione. Ideale per:

  • Ricerca per regione/provincia/comune
  • Ricerca per coordinate geografiche
  • Analisi geografiche

Esempi di Query

Ricerca Semplice per Nome

curl -X POST https://nitro.italianonprofit.it/api/v1/organizations/search \
  -H "Authorization: Bearer <tuo-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "index": "organization-serp*",
    "body": {
      "query": {
        "match": {
          "name": "associazione"
        }
      },
      "size": 20
    }
  }'

Ricerca con Filtri Multipli

curl -X POST https://nitro.italianonprofit.it/api/v1/organizations/search \
  -H "Authorization: Bearer <tuo-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "index": "organization-entity*",
    "body": {
      "query": {
        "bool": {
          "must": [
            {
              "match": {
                "name": "associazione"
              }
            }
          ],
          "filter": [
            {
              "term": {
                "legal_status": "APS"
              }
            },
            {
              "range": {
                "founded_year": {
                  "gte": 2020
                }
              }
            }
          ]
        }
      },
      "size": 10,
      "sort": [
        {
          "name.keyword": {
            "order": "asc"
          }
        }
      ]
    }
  }'

Ricerca per Codice Fiscale

curl -X POST https://nitro.italianonprofit.it/api/v1/organizations/search \
  -H "Authorization: Bearer <tuo-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "index": "organization-entity*",
    "body": {
      "query": {
        "term": {
          "tax_code": "12345678901"
        }
      },
      "size": 1
    }
  }'

Ricerca con Aggregazioni

curl -X POST https://nitro.italianonprofit.it/api/v1/organizations/search \
  -H "Authorization: Bearer <tuo-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "index": "organization-entity*",
    "body": {
      "query": {
        "match_all": {}
      },
      "size": 0,
      "aggs": {
        "per_status": {
          "terms": {
            "field": "legal_status.keyword",
            "size": 10
          }
        }
      }
    }
  }'

Ricerca Geografica

curl -X POST https://nitro.italianonprofit.it/api/v1/organizations/search \
  -H "Authorization: Bearer <tuo-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "index": "map-serp*",
    "body": {
      "query": {
        "bool": {
          "must": [
            {
              "match": {
                "name": "associazione"
              }
            }
          ],
          "filter": [
            {
              "term": {
                "region": "Lombardia"
              }
            }
          ]
        }
      }
    }
  }'

Paginazione

Per gestire grandi set di risultati, usa i parametri from e size:

{
  "index": "organization-serp*",
  "body": {
    "query": {
      "match_all": {}
    },
    "from": 0,
    "size": 20
  }
}

Pagina 1: from: 0, size: 20 (risultati 1-20) Pagina 2: from: 20, size: 20 (risultati 21-40) Pagina 3: from: 40, size: 20 (risultati 41-60)

Ordinamento

Puoi ordinare i risultati usando il campo sort:

{
  "index": "organization-serp*",
  "body": {
    "query": {
      "match": {
        "name": "associazione"
      }
    },
    "sort": [
      {
        "name.keyword": {
          "order": "asc"
        }
      },
      {
        "_score": {
          "order": "desc"
        }
      }
    ]
  }
}

Gestione Errori

Errore di Validazione

Se l'indice o il body non sono validi:

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Dati non validi",
    "details": {
      "index": {
        "_errors": [
          "L'indice deve iniziare con 'map-serp' o 'organization-entity' o 'organization-serp'"
        ]
      }
    }
  }
}

Elasticsearch Non Disponibile

Se Elasticsearch non è disponibile:

{
  "status": "error",
  "error": {
    "code": "ELASTICSEARCH_UNAVAILABLE",
    "message": "Elasticsearch v9 non disponibile",
    "details": {
      "version": "v9"
    }
  }
}

Best Practices

  1. Scegli l'indice corretto: Usa organization-serp* per ricerche full-text, organization-entity* per query strutturate
  2. Limita i risultati: Usa sempre size per limitare il numero di risultati (default: 10, max consigliato: 100)
  3. Usa filtri invece di query quando possibile: I filtri sono più veloci e cacheabili
  4. Implementa paginazione: Per grandi set di dati, usa from e size
  5. Gestisci gli errori: Controlla sempre il campo status nella risposta

Documentazione Correlata

Risorse Utili

Aggiornamento Token

Come rinnovare i token di accesso usando i refresh token

Trasparenza delle Organizzazioni Non Profit

Il programma di trasparenza di italianonprofit.it è un sistema volontario che permette alle organizzazioni non profit italiane di rendere pubblici i propri dati organizzativi, economici e di impatto sociale attraverso la compilazione di moduli strutturati.