search.ch
  1. Richiesta
  2. Formato risposta
  3. Status codes HTTP
  4. Richiedere una nuova chiave API
  5. Condizioni d'utilizzo

Specificazioni API

Richieste

Le richieste vengono inviate con l'HTTP-URIs all'API. Questo modo di procedere corrisponde al concetto di REST.

https://tel.search.ch/api/?was=john+meier&key=Vostra chiave

Una richiesta formale e corretta riprestina lo stato HTTP 200. Richieste imprecise o con l'API-Key non valida vengono risposte con l'HTTP-Statuscodes corrispondente.

Il Query-URI sostiene i parametri seguenti. Tutti i valori devono essere codificati correttamente come da URL.

ParametroOpzionaleDescrizione
wasnoPercorso generale. Ricerca di nomi, rubriche o numeri di telefono
woLimitazioni geografiche nella ricerca.
Può essere una via, un luogo, un NPA o un'abbreviazione di un cantone.
qRicerca a was e wo.
privat1 = Ricerca di iscrizioni private, 0 = Iscrizioni private vengono escluse. Default = 1
firma1 = Ricerca d'iscrizioni di ditte, 0 = Iscrizioni di ditte vengono escluse. Default = 1
posPosizione delle prime iscrizioni nel rilevamento.
Nelle richieste con più di un risultato viene usato maxnum.
maxnumQuantità di risultati nel Feed.
L'output è limitato ad un massimo di 200 iscrizioni.
keyAPI-Key. La chiave potete richiederla con il nostro formulario.
langLinguaggio. Valori possibili: de,fr,it,en
count_only1 = solo il numero di risultati (veloce)

Formato risposta

I risultati API sono forniti sotto forma di Atom-Feeds. Il Feed viene completato con un proprio Namespaces per gli elementi OpenSearch e per i campi specifici di tel.search.ch.

I seguenti elementi OpenSearch sono assogettati direttamente agli elementi <feed>:

openSearch:totalResults
Totale delle iscrizioni trovate
openSearch:startIndex
Posizione delle prime iscrizioni nel set dei risultati. Partenza da 1
openSearch:itemsPerPage
Quantità di iscrizioni mostrate nel Feed. Ciò corrisponde al parametro maxnum.
openSearch:Query
La rappresentazione dell'attuale richiesta.
Form: <openSearch:Query role="request" searchTerms="..." startPage="1" />

Se con l'attuale criterio di ricerca non viene trovato un risultato, viene inserito un Query-Element supplementare con una proposta di correzione.
Esempio: <openSearch:Query role="correction" searchTerms="Panetteria" totalResults="5256" />

I seguenti elementi sono assoggettati ad un'iscrizione nel Feed (/feed/entry) e rappresentano un set di dati trovati:

FeldAPI-Key necessariaDescrizione
/feed/entry/idnoEvidente identificatore secondo RFC 4287
/feed/entry/publishednoData di pubblicazione nel Timestamp Format (RFC 3339)
Per esempio 2007-01-09T08:00:00Z
/feed/entry/updatednoUltima mutazione nel formato Timestamp Format (RFC 3339)
Per esempio 2007-01-12T14:32:11Z
/feed/entry/titlenein Titolo dell'iscrizione
Nome della persona o dell'organizzazione
/feed/entry/contentnoRiassunto dell'iscrizione in Plaintext
/feed/entry/author/namenoAutore dell'iscrizione (secondo RFC 4287)
/feed/entry/link/@rel='alternate'noLink sulla pagina dei dettagli dell'iscrizione di tel.search.ch
/feed/entry/link/@rel='edit'noLink sulla pagina di correzione dell'iscrizione di tel.search.ch
/feed/entry/link/@type='text/x-vcard'noURL per il download come VCard
/feed/entry/tel:posPosizione dell'iscrizione nel set dei risultati
/feed/entry/tel:idEvidente ID-tel.search.ch dell'iscrizione
/feed/entry/tel:typejaTipo d'iscrizione: Persona o organizzazione
/feed/entry/tel:orgjaOrganizzaazione
/feed/entry/tel:nameCognome della persona risp. nome della ditta/organizzazione
/feed/entry/tel:firstnamejaNome della persona
/feed/entry/tel:subnamejaNome aggiuntivo
/feed/entry/tel:maidennameCognome da nubile della persona
/feed/entry/tel:occupationProfessione della persona, nome supplementare per le iscrizioni di ditte
/feed/entry/tel:categoryRubrica per le iscrizioni di ditte (è possibile indicare più di un elemento)
/feed/entry/tel:streetNome della via
/feed/entry/tel:streetnoNumero della via
/feed/entry/tel:poboxCasella postale
/feed/entry/tel:zipNumero postale d'avviamento
/feed/entry/tel:cityLuogo
/feed/entry/tel:cantonAbbreviazione del cantone (ZH,BE,AG,...)
/feed/entry/tel:nopromoja* Non desidera pubblicità
/feed/entry/tel:phoneNumero di telefono con prefisso nazionale
/feed/entry/tel:extra/@type='fax'Numero del fax (opzionale)
/feed/entry/tel:extra/@type='email'indirizzo e-mail (opzionale)
/feed/entry/tel:extra/@type='website'URL della pagina web (opzionale)
/feed/entry/tel:extra/@type='skype' Nome Skype (opzionale)
/feed/entry/tel:extra/@type='icq|msn|aim|yahoo'Instant-Messenger-Name (opzionale)

Un esempio di Reponse in Atom-Format : api-response.xml

HTTP Status Codes

Ogni domanda viene risposta con uno Status-Code secondo l'HTTP-Spezifikation. Qui sotto trovate gli Status-Code più usati e il suo significato nell'API-Requests:

CodeDescrizione
200 OKNessun errore
400 BAD REQUEST
401
Request sbagliate
p.es. manca il paramento o l'Headers
403 FORBIDDENL'autorizzazione dell'API-Keys è fallita
404 NOT FOUNDNessun API-Feed in questo URL

Se l'autorizzazione dell'API-Keys fallisce, troverete nel Body una spiegazione supplementare del problema sotto forma di Atom-Feed con dei campi specifici:

CodeBeschrieb
/feed/tel:errorCodeErrore di codice
/feed/tel:errorReasonMotivo dell'errore
/feed/tel:errorMessageSpiegazione dell'errore

Un esempio di una segnalazione d'errore in Atom-Format: api-error