Documentazione API (beta)

I metodi delle nostre API ti permettono di ottenere, in tempo reale, tutti i dati sulle nostre Startup, compresa la classifica (Hot), il sistema di tagging e da quello di ricerca. Accettiamo delle semplici chiamate con parametri GET e ti rispondiamo utilizzando il formato JSON. In questa pagina ti illustriamo tutti i metodi disponibili ed i parametri richiesti, oltre agli esempi pratici realizzati utilizzando la tecnica AJAX (tramite la libreria jQuery) e/o il linguaggo server-side PHP. Guarda gli esempi di utilizzo. Per autenticare ogni richiesta è necessario ottenere una API Key gratuita.

Specifiche comuni

Tipo di richiesta: HTTP GET
URL: http://www.pitchcloud.it/public-api
Formato di risposta: JSON



Parametri necessari

L'unico parametro necessario è key, la chiave che PitchCloud ti ha fornito. Se non hai ancora una Chiave API puoi richiederla qui.

key La chiave che PitchCloud ti ha fornito. Se non hai ancora una Chiave API puoi richiederla qui.
m Il nome del metodo da richiamare, tra quelli elencati di seguito.



Metodi API

Ecco la lista dei metodi pubblici che puoi utilizzare:



startup.get

Risponde con i dati di una singola Startup specificata dal parametro id.

Parametri richiesti

id Questo parametro può essere di due tipi: numerico se si conosce l'id diretto della Startup (ad esempio, ottenuto da startups.search) oppure come stringa, utilizzando il nome sintetico della startup usato negli Url di PitchCloud (es. "splitgigs" da www.pitchcloud.it/startup/splitgigs).
Risposta:
{
	"idstartup":"6",
	"nomestartup":"SplitGigs",
	"descstartup":"Looking for Gigs to Play? SplitGigs is a
	social network that helps emerging band[..]",
	"embedtype":"youtube",
	"codevideo":"XNkjCYO394M",
	"embedbig":"[ html di embedding youtube con player da 960x558px ]" ,
	"embedmid":"[ html di embedding youtube con player da 660x397px ]",
	"embedthumb":"http:\/\/img.youtube.com\/vi\/XNkjCYO394M\/0.jpg",
	"urlstartup":"http:\/\/www.splitgigs.com",
	"twittername":"splitgigs",
	"votiup":"14",
	"votidown":"1",
	"diffvotazione":"13",
	"commenti":"2",
	"featured":"1",
	"datasubmit":"1282747816",
	"urlnamestartup":"splitgigs",
	"tagstext":"social, music, gig, live, art, manager, 
	booking, play, guitar, rock, label, record, network",
	"featureddata":"1288173931",
	"isking":"0",
	"nomepartner":"",
	"urlpartner":"",
	"logopartner":""
}
								

startups.get

Risponde con i dati su una o più Startup. Nessun parametro (oltre key) è richiesto. Tuttavia ci sono parametri opzionali.

Parametri opzionali

type Il tipo di Startups selezionate. Questo parametro può essere "APPROVED" oppure "FEATURED". Se non viene usato (oppure non è contemplato dal sistema) viene impostato di default ad "APPROVED".

ob Il tipo di ordinamento dei risultati. È possibile impostarlo su "data" (Data di inserimento), "rilevanza", "commenti" (numero di commenti) o "voto" (differenza tra voti up e down). Di default è impostato su "data".

om Il metodo di ordinamento dei risultati, dal maggiore al minore o viceversa. Può essere impostato su "up" (oppure usando "ASC") o su "down" (oppure usando "DESC").

page Il numero di pagina con i risultati da selezionare. Di default è impostato a 1 (uno).

perpage Il numero di elementi da selezionare per singola pagina. Di default è impostato a 10 (dieci).

Risposta:
[
	{
		"idstartup":"23",
		"nomestartup":"egoagosys",
		"descstartup":"Egoagosys nasce nel 2006 all'interno [..]",
		"embedtype":"youtube",
		"codevideo":"ZK4ha25hSZ8",
		"embedbig":"..",
		"embedmid":"..",
		"embedthumb":"http:\/\/img.youtube.com\/vi\/ZK4ha25hSZ8\/0.jpg",
		"urlstartup":"http:\/\/egoagosys.com",
		"twittername":"egoagosys",
		"votiup":"6",
		"votidown":"1",
		"diffvotazione":"5",
		"commenti":"0",
		"featured":"0",
		"datasubmit":"1289034862",
		"urlnamestartup":"egoagosys",
		"tagstext":"open-source,crm,voip,cloud,on-demand",
		"featureddata":"0",
		"isking":"0",
		"nomepartner":"",
		"urlpartner":"",
		"logopartner":""
	},{
		"idstartup":"22",
		"nomestartup":"NextStyler",
		"descstartup":"NextStyler è una vetrina [..]",
		"embedtype":"vimeo",
		"codevideo":"13387866",
		"embedbig":"..",
		"embedmid":"..",
		"embedthumb":"http:\/\/b.vimeocdn.com\/ts\/979\/537\/97953728_200.jpg",
		"urlstartup":"http:\/\/www.nextstyler.com",
		"twittername":"Next_Styler",
		"votiup":"38",
		"votidown":"2",
		"diffvotazione":"36",
		"commenti":"3",
		"featured":"1",
		"datasubmit":"1288810202",
		"urlnamestartup":"nextstyler",
		"tagstext":"social, fashion, community, moda, stylist, fashion [..]",
		"featureddata":"1288812449",
		"isking":"1",
		"nomepartner":"",
		"urlpartner":"",
		"logopartner":""
	}
]
								

startups.search

Cerca all'interno del nostro sistema la corrispondenza di uno o più termini. La ricerca è estesa anche ai Tag. Il sistema di parametri di riferimento è analogo a startups.get con l'aggiunta di un solo parametro e la deprecazione del parametro "type":

Parametri richiesti

search La stringa con l'oggetto della ricerca. Una stringa vuota restituirà un'errore.

Parametri opzionali
ob Il tipo di ordinamento dei risultati. È possibile impostarlo su "data" (Data di inserimento), "rilevanza", "commenti" (numero di commenti) o "voto" (differenza tra voti up e down). Di default è impostato su "data".

om Il metodo di ordinamento dei risultati, dal maggiore al minore o viceversa. Può essere impostato su "up" (oppure usando "ASC") o su "down" (oppure usando "DESC").

page Il numero di pagina con i risultati da selezionare. Di default è impostato a 1 (uno).

perpage Il numero di elementi da selezionare per singola pagina. Di default è impostato a 10 (dieci).

Risposta: Analoga a quella di startups.get




startups.hot.get

Seleziona le prime 3 Startup in Classifica (hot). Come nella pagina delle hot Startups.
Questo metodo non ha alcun parametro.

Risposta: Analoga a quella di startups.get




startups.get.bypartner

Seleziona tutte le Startup che hanno un riferimento ad un dato Partner di PitchCloud.

Parametri richiesti

partner (Stringa) L'identificativo del partner. Forniamo selettivamente questo parametro ai nostri Partner.

Risposta: Analoga a quella di startups.get




startups.get.featured

Seleziona tutte le Startup che mostriamo in home page, in "Primo Piano".
Questo metodo non ha alcun parametro.

Risposta: Analoga a quella di startups.get




startup.shuffle

Seleziona una Startup in modo casuale.
Questo metodo non ha alcun parametro.

Risposta: Analoga a quella di startup.get




startup.comments.get

Seleziona tutti i commenti di una Startup ordinati dal più vecchio al più nuovo.

Parametri richiesti

id Questo parametro può essere di due tipi: numerico se si conosce l'id diretto della Startup (ad esempio, ottenuto da startups.search) oppure come stringa, utilizzando il nome sintetico della startup usato negli Url di PitchCloud (es. "splitgigs" da www.pitchcloud.it/startup/splitgigs).

Risposta:
[
	{
		"idcommento":"33",
		"startup":"22",
		"nome":"ale",
		"twitter":"",
		"twitteravatar":"",
		"urlcommento":"",
		"testo":"è un'iniziativa grandiosa! [..]",
		"datacommento":"1288829948"
	},{
		"idcommento":"35",
		"startup":"22",
		"nome":"Mary",
		"twitter":"Next_Styler",
		"twitteravatar":"http:\/\/a2.twimg.com\/[..]\/logoCS2.jpg",
		"urlcommento":"http:\/\/blog.nextstyler.com\/",
		"testo":"grazie mille ale :) sarà online [..]",
		"datacommento":"1288870162"
	},{
		"idcommento":"36",
		"startup":"22",
		"nome":"Maurizia",
		"twitter":"",
		"twitteravatar":"",
		"urlcommento":"",
		"testo":"Ci voleva un progetto del genere. Bravissimi!",
		"datacommento":"1288871541"
	}
]
								



startups.get.bytag

Seleziona tutte le Startup taggate con il tag richiesto.

Parametri richiesti

tag (Stringa) Il nome del tag (es. "social").

ob Il tipo di ordinamento dei risultati. È possibile impostarlo su "data" (Data di inserimento), "rilevanza", "commenti" (numero di commenti) o "voto" (differenza tra voti up e down). Di default è impostato su "data".

om Il metodo di ordinamento dei risultati, dal maggiore al minore o viceversa. Può essere impostato su "up" (oppure usando "ASC") o su "down" (oppure usando "DESC").

page Il numero di pagina con i risultati da selezionare. Di default è impostato a 1 (uno).

perpage Il numero di elementi da selezionare per singola pagina. Di default è impostato a 10 (dieci).

Risposta: Analoga a quella di startups.get



Esempi di chiamata

Come già detto, il nostro sistema fornisce un flusso in formato JSON. Questo formato ti permette di usare e manipolare i dati da parte di qualsiasi linguaggio, sia client-side come javascript, che server-side. In questi esempi useremo la libreria jQuery per usare in modo semplice la tecnica AJAX e PHP come linguaggio lato server.


/*
	Effettuiamo delle semplici chiamata utilizzando il metodo jQuery.getJSON
	http://api.jquery.com/jQuery.getJSON
*/

//Selezioniamo le Startup prime in classifica
$.getJSON(
	"http://www.pitchcloud.it/public-api",
	{
		key: 'CHIAVE_API',
		m: 'startups.hot.get'
	}
	function(startups) {
		//Iteriamo attraverso i risultati
		for (var indice in startups) {
			nomeStartup=startups[indice].nomestartup;
			alert('Posizione numero '+(i+1)+': '+nomeStartup);
		}
	}
);


//Selezioniamo le Startup taggate "social" ordinate dalla
//più rilevante alla meno rilevante
$.getJSON(
	"http://www.pitchcloud.it/public-api",
	{
		key: 'CHIAVE_API',
		m: 'startups.get.bytag',
		tag: 'social',
		ob: 'rilevanza',
		om: 'down' //default
	}
	function(startups) {
		alert('Ho trovato '+startups.length+' Startup.');
		alert('La migliore Startup taggata "social": 
		'+startups[0].nomestartup);
	}
);


						
Ora illustriamo le stesse funzioni usando come linguaggio server-side PHP:

							
//Selezioniamo le Startup prime in classifica

//impostiamo alcuni parametri
$apiKey='CHIAVE_API';
$metodo='startups.hot.get';
$urlApi='http://www.pitchcloud.it/public-api';

//prendiamo il contenuto statico usando file_get_contents()
$resource=file_get_contents($urlApi."?key=".$apiKey."&m=".$metodo);

//traduciamo i dati da JSON ad array associativo
$startups=json_decode($resource,true);

//iteriamo attraverso i risultati
foreach($startups as $indice => $startup) {
	$nomeStartup=$startup['nomestartup'];
	echo 'Posizione numero '.($indice+1).': '.$nomeStartup.'\n';
}



//Selezioniamo le Startup taggate "social" ordinate dalla
//più rilevante alla meno rilevante

//impostiamo alcuni parametri
$apiKey='CHIAVE_API';
$metodo='startups.get.bytag';
$urlApi='http://www.pitchcloud.it/public-api';
$tag='social';
$ob='rilevanza'; 
$om='down'; //default

//prendiamo il contenuto statico usando file_get_contents()
$resource=file_get_contents($urlApi."?key=".$apiKey."&m=".$metodo."&tag=".
$tag."&ob=".$ob."&om=".$om);

//traduciamo i dati da JSON ad array associativo
$startups=json_decode($resource,true);

//Stampiamo a schermo
echo 'Ho trovato '.count($startups).' Startup.\n'	
echo 'La migliore Startup taggata "social": '$startups[0]['nomestartup'];	
							
						



Controllo degli errori

Il sistema restituisce, in caso di errori, un semplice array monoelemento con indice 'error', il cui valore è, appunto, il tipo di errore generato:

{
	"error":"motivo dell'errore.",
}
									
Ecco alcuni esempi di controllo dell'errore, nei linguaggi precedentemente citati negli esempi. Controllo dell'errore in Javascript:

$.getJSON(
	"http://www.pitchcloud.it/public-api",
	{
		key: 'CHIAVE_API',
		m: 'startups.hot.get'
	}
	function(startups) {
		if ('error' in startups) {
			alert("Si è verificato un'errore: "+startups.error);
		} else {
			for (var indice in startups) {
				nomeStartup=startups[indice].nomestartup;
				alert('Posizione numero '+(i+1)+': '+nomeStartup);
			}
		}
	}
);
						
						
..ed in PHP:

$apiKey='CHIAVE_API';
$metodo='startups.hot.get';
$urlApi='http://www.pitchcloud.it/public-api';

$resource=file_get_contents($urlApi."?key=".$apiKey."&m=".$metodo);

$startups=json_decode($resource,true);

if ($startups['error'] != '') {
	echo "Si è verificato un'errore: ".$startups['error'];
} else {
	foreach($startups as $indice => $startup) {
		$nomeStartup=$startup['nomestartup'];
		echo 'Posizione numero '.($indice+1).': '.$nomeStartup.'\n';
	}
}							
						





Se dovessi avere dubbi o domande, contattaci pure.

Happy coding!