Le richieste vengono inviate con l'HTTP-URIs all'API. Questo modo di procedere corrisponde al concetto di REST.
https://search.ch/tel/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.
| Parametro | Opzionale | Descrizione |
| was | no | Percorso generale. Ricerca di nomi, rubriche o numeri di telefono |
| wo | sì | Limitazioni geografiche nella ricerca. Può essere una via, un luogo, un NPA o un'abbreviazione di un cantone. |
| q | sì | Ricerca a was e wo. |
| privat | sì | 1 = Ricerca di iscrizioni private, 0 = Iscrizioni private vengono escluse. Default = 1 |
| firma | sì | 1 = Ricerca d'iscrizioni di ditte, 0 = Iscrizioni di ditte vengono escluse. Default = 1 |
| pos | sì | Posizione delle prime iscrizioni nel rilevamento. Nelle richieste con più di un risultato viene usato maxnum. |
| maxnum | sì | Quantità di risultati nel Feed. L'output è limitato ad un massimo di 200 iscrizioni. |
| key | sì | API-Key. La chiave potete richiederla con il nostro formulario. |
| lang | sì | Linguaggio. Valori possibili: de,fr,it,en |
| count_only | sì | 1 = solo il numero di risultati (veloce) |
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>:
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:
| Feld | API-Key necessaria | Descrizione |
| /feed/entry/id | no | Evidente identificatore secondo RFC 4287 |
| /feed/entry/published | no | Data di pubblicazione nel Timestamp Format (RFC 3339) Per esempio 2007-01-09T08:00:00Z |
| /feed/entry/updated | no | Ultima mutazione nel formato Timestamp Format (RFC 3339) Per esempio 2007-01-12T14:32:11Z |
| /feed/entry/title | no | Titolo dell'iscrizione Nome della persona o dell'organizzazione |
| /feed/entry/content | no | Riassunto dell'iscrizione in Plaintext |
| /feed/entry/author/name | no | Autore dell'iscrizione (secondo RFC 4287) |
| /feed/entry/link/@rel='alternate' | no | Link sulla pagina dei dettagli dell'iscrizione di tel.search.ch |
| /feed/entry/link/@rel='edit' | no | Link sulla pagina di correzione dell'iscrizione di tel.search.ch |
| /feed/entry/link/@type='text/x-vcard' | no | URL per il download come VCard |
| /feed/entry/tel:pos | sì | Posizione dell'iscrizione nel set dei risultati |
| /feed/entry/tel:id | sì | Evidente ID-tel.search.ch dell'iscrizione |
| /feed/entry/tel:type | si | Tipo d'iscrizione: Persona o organizzazione |
| /feed/entry/tel:org | si | Organizzaazione |
| /feed/entry/tel:name | sì | Cognome della persona risp. nome della ditta/organizzazione |
| /feed/entry/tel:firstname | si | Nome della persona |
| /feed/entry/tel:subname | si | Nome aggiuntivo |
| /feed/entry/tel:maidenname | sì | Cognome da nubile della persona |
| /feed/entry/tel:occupation | sì | Professione della persona, nome supplementare per le iscrizioni di ditte |
| /feed/entry/tel:category | sì | Rubrica per le iscrizioni di ditte (è possibile indicare più di un elemento) |
| /feed/entry/tel:street | sì | Nome della via |
| /feed/entry/tel:streetno | sì | Numero della via |
| /feed/entry/tel:pobox | sì | Casella postale |
| /feed/entry/tel:hamlet | sì | Borgo |
| /feed/entry/tel:zip | sì | Numero postale d'avviamento |
| /feed/entry/tel:city | sì | Luogo |
| /feed/entry/tel:canton | sì | Abbreviazione del cantone (ZH,BE,AG,...) |
| /feed/entry/tel:nopromo | si | * Non desidera pubblicità |
| /feed/entry/tel:phone | sì | Numero di telefono con prefisso nazionale |
| /feed/entry/tel:extra/@type='fax' | sì | Numero del fax (opzionale) |
| /feed/entry/tel:extra/@type='email' | sì | indirizzo e-mail (opzionale) |
| /feed/entry/tel:extra/@type='website' | sì | URL della pagina web (opzionale) |
| /feed/entry/tel:extra/@type='skype' | sì | Nome Skype (opzionale) |
| /feed/entry/tel:extra/@type='icq|msn|aim|yahoo' | sì | Instant-Messenger-Name (opzionale) |
Un esempio di Reponse in Atom-Format : api-response.xml
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:
| Code | Descrizione |
| 200 OK | Nessun errore |
| 400 BAD REQUEST 401 | Request sbagliate p.es. manca il paramento o l'Headers |
| 403 FORBIDDEN | L'autorizzazione dell'API-Keys è fallita |
| 404 NOT FOUND | Nessun 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:
| Code | Beschrieb |
| /feed/tel:errorCode | Errore di codice |
| /feed/tel:errorReason | Motivo dell'errore |
| /feed/tel:errorMessage | Spiegazione dell'errore |
Un esempio di una segnalazione d'errore in Atom-Format: api-error