Documentazione API

L'API PANORAMA consente di visualizzare sul proprio sito web i casi di studio di soluzioni selezionate. È possibile richiamare/accedere solo ad alcune parti della descrizione della soluzione, tra cui diversi filtri e opzioni di ordinamento per richiedere i dati delle soluzioni desiderate. Questa documentazione vi aiuta a utilizzare l'API PANORAMA e a trovare le impostazioni corrette.

Autenticazione

Per utilizzare l'API, aggiungere il proprio token di accesso all'API PANORAMA alla richiesta API:

https://panorama.solutions/en/api/v1/solutions?api_key=1234

Utilizzo di base e lingua delle soluzioni

L'URL dell'API PANORAMA è:

https://panorama.solutions/{prefisso_lingua}/api/v1/soluzioni

Il prefisso della lingua può essere impostato su una delle tre lingue utilizzate in PANORAMA: en = inglese, fr = francese ed es = spagnolo. Il prefisso della lingua determina in quale lingua vengono elencate le soluzioni: impostandolo su "en", le soluzioni verranno elencate con la loro traduzione in inglese, purché esista una traduzione in inglese, altrimenti la soluzione verrà elencata nella sua lingua originale, che può essere il francese o lo spagnolo.

https://panorama.solutions/en/api/v1/solutions

È possibile modificare questo comportamento e forzare la ricezione delle sole soluzioni pubblicate in una lingua specifica aggiungendo un filtro alla richiesta API. Ad esempio: Se si desidera ricevere le soluzioni tradotte in spagnolo, utilizzare la seguente richiesta API:

https://panorama.solutions/es/api/v1/solutions?language[]=es

Tenete presente quanto segue:

  • I filtri vengono aggiunti utilizzando il nome del filtro ("lingua"), seguito dalle parentesi quadre [], dal segno di uguale e dal valore. Per saperne di più, si veda più avanti.
  • Se si aggiunge il filtro "lingua", non si ricevono automaticamente i testi tradotti corrispondenti. Ricordate di modificare il prefisso della lingua per ricevere le soluzioni tradotte nella lingua che preferite.
  • È possibile aggiungere più parametri di richiesta aggiungendoli con "&" alla richiesta API.
https://panorama.solutions/es/api/v1/solutions?language[]=es&altro_filtro[]=123

Ordinamento

È possibile modificare l'ordinamento delle soluzioni ricevute dalla nostra API. Per l'ordinamento, sono disponibili due parametri: "sort_by" e "sort_order" (che è opzionale). Per "sort_order" è possibile impostare "ASC" per l'ordine ascendente e "DESC" per l'ordine discendente. Tenere presente che i valori "ASC" e "DESC" per il parametro "sort_order" devono essere scritti in maiuscolo. Quando non è impostato il parametro "sort_order", ogni opzione di "sorty_by" ha un valore predefinito. Le opzioni per il parametro "sort_by" sono le seguenti:

Se si desidera ottenere le soluzioni in ordine alfabetico crescente, si deve aggiungere alla richiesta quanto segue:


https://panorama.solutions/en/api/v1/solutions?sort_by=title_field&sort_order=ASC
  • changed: ordinamento in base alla data in cui le soluzioni sono state modificate l'ultima volta per ottenere la prima (o l'ultima) soluzione più recente. Ordine predefinito: DESC
  • campo_titolo: Ordine alfabetico per titolo della soluzione. Ordine predefinito: ASC
  • search_api_relevance: Pertinenza delle soluzioni relative a un termine di ricerca - questa opzione di ordinamento è utile solo se si esegue una query rispetto alla nostra ricerca, che viene spiegata più avanti. Ordine predefinito: DESC (prima l'alta rilevanza)

Filtri

È possibile utilizzare molti filtri per filtrare solo le soluzioni di interesse per l'utente.

È importante notare che i filtri devono essere aggiunti tra parentesi quadre alla richiesta API, poiché ogni filtro può essere utilizzato più volte. Ad esempio, per ottenere le soluzioni collegate alla categoria "Agro-ecosistema" (il cui id è 370) dal filtro "Ecosistema", è necessario aggiungere quanto segue alla richiesta API:

https://panorama.solutions/en/api/v1/solutions?ecosystem[]=370

In questo modo è possibile raccogliere le soluzioni collegate a diverse categorie all'interno del filtro "Ecosistema". Se siete interessati alle soluzioni relative a "Agro-ecosistema" e "Ecosistemi desertici" (che ha l'id 33), potete utilizzare la seguente richiesta API:

https://panorama.solutions/en/api/v1/solutions?ecosystem[]=370&ecosistema[]=33

Per ottenere tutti i filtri che si desidera utilizzare si può utilizzare la pagina PANORAMA Explorer - quando si utilizza l'explorer per il filtraggio nella barra degli indirizzi del browser si trova un URL con tutti i parametri necessari. È possibile utilizzare questi parametri URL per aggiungerli al percorso di richiesta dell'API di PANORAMA. Tenere presente che in questa API sono disponibili altri filtri.

Ricerca con termini di ricerca/parole chiave

Analogamente alla pagina di PANORAMA Explorer, è possibile eseguire una ricerca per trovare soluzioni correlate a una o più parole chiave/termini di ricerca. A tale scopo, utilizzare il parametro "parola chiave":

https://panorama.solutions/en/api/v1/solutions?keyword=marine

È possibile aggiungere più parole chiave per restringere la ricerca, aggiungendo parole chiave separate da spazi codificati dall'URL, in modo che una ricerca per "pesca marina" appaia come la seguente:

https://panorama.solutions/en/api/v1/solutions?keyword=marine%20fisheries

Per le richieste API con termini di ricerca si dovrebbe sempre aggiungere il parametro di ordinamento "sort_by" con il valore "search_api_relevance" per ottenere prima le soluzioni più pertinenti alla ricerca:

https://panorama.solutions/en/api/v1/solutions?keyword=marine%20fisheries&sort_by=search_api_relevance

Paginazione

In ogni risposta si riceveranno al massimo 20 soluzioni. L'API offre una paginazione che consente di ricevere le 20 soluzioni successive aggiungendo il parametro "page" alla richiesta:

https://panorama.solutions/en/api/v1/solutions?page=2

La risposta non include alcuna informazione sulla presenza di soluzioni nella pagina 2, per cui è necessario verificarlo da soli quando si chiama la pagina successiva.

Richiesta di una singola soluzione per ID o WDPA

È possibile usare i parametri &nid=NODE_ID e &wdpa=NODE_ID

&nid
Per richiedere una singola soluzione è possibile utilizzare il filtro &nid
È possibile trovare l'ID richiedendo l'API (fa parte dell'oggetto solution) o guardando il codice sorgente HTML di una soluzione (vedere il tag body)

https://panorama.solutions/es/api/v1/solutions?api_key=123456&nid=115

&wdpa
Aree protette Le soluzioni contengono l'ID WDPA del pianeta protetto.
La risposta includerà tutte le soluzioni con l'ID corrispondente.

https://panorama.solutions/es/api/v1/solutions?api_key=123456&wdpa=115

Richiesta di soluzioni in base ai codici ISO dei Paesi

Utilizzare il parametro &country_iso_2 per richiedere le soluzioni filtrate per paese iso

https://panorama.solutions/es/api/v1/solutions?api_key=123456&country_iso_2=DE

Richiesta di soluzioni per titolo del portale

Utilizzare il parametro &portal_title per richiedere le soluzioni filtrate in base al portale a cui sono assegnate. Il titolo del portale si trova come parte dell'URL che appartiene a una pagina del portale/comunità tematica.

Ad esempio https://panorama.solutions/en/portal/protected-areas
dove protected-areas è il titolo del portale corrispondente che può essere usato come filtro API.

https://panorama.solutions/es/api/v1/solutions?api_key=123456&portal_title=protected-areas

Richiesta di soluzioni per ID portale

Utilizzate il parametro &portal_id per richiedere le soluzioni filtrate in base all'ID del portale a cui sono assegnate. L'ID del portale si trova nell'URL quando si modifica una pagina del portale.

https://panorama.solutions/es/api/v1/solutions?api_key=123456&portal_id=4673