Anfragen werden als HTTP-URIs ans API gesendet. Dies entspricht dem Konzept von REST.
Wenn Sie einen API-Schlüssel bestellen, können Sie mehr Anfragen pro Tag machen.
https://search.ch/tel/api/?was=john+meier&key=Ihr Schlüssel
Eine formal korrekte Anfrage gibt den Status HTTP 200 zurück. Fehlerhafte Requests oder Anfragen mit ungültigen API-Keys werden mit den ensprechenden HTTP-Statuscodes beantwortet.
Die Query-URI unterstützt folgende Parameter. Alle Werte müssen korrekt URL-kodiert sein.
| Parameter | Optional | Beschrieb |
| was | nein | Allgemeiner Suchstring. Suche nach Namen, Rubriken oder Telefonnummern |
| wo | ja | Geografische Einschränkung der Suche. Dies kann eine Strasse, Ortsbezeichnung, Postleitzahl oder ein Kantonskürzel sein. |
| q | ja | Für Einfeldsuche. Die Begriffe werden in was und wo gesucht. |
| privat | ja | 1 = Suche in Privateinträgen, 0 = Privateinträge werden ausgeschlossen. Default = 1 |
| firma | ja | 1 = Suche in Firmeneinträgen, 0 = Firmeneinträge werden ausgeschlossen. Default = 1 |
| pos | ja | Position des ersten Eintrags in der Abfrage. Wird bei Anfragen mit mehr Resultaten als maxnum verwendet. |
| maxnum | ja | Anzahl Resultate im Feed. Die Ausgabe ist aber auf maximal 200 Einträge beschränkt. |
| key | ja | API-Key. Einen Schlüssel können Sie über unser Formular anfordern. |
| lang | ja | Ausgabesprache. Mögliche Werte: de,fr,it,en Übersetzbare Informationen wie z.B. Kategorien werden in der angegebenen Sprache ausgegeben. |
| count_only | ja | 1 = nur die Zahl der Resultate liefern (schneller) |
API-Resultate werden in Form eines Atom-Feeds geliefert. Der Feed wird mit eigenen Namespaces für OpenSearch-Elemente und tel.search.ch-spezifischen Feldern ergänzt.
Die folgenden OpenSearch-Elemente sind direkt dem <feed>-Element untergeordnet:
Werden mit dem aktuellen Suchbegriff keine Resultate gefunden, wird ein zusätzliches Query-Element mit einem Korrekturvorschlag eingefügt.
Beispiel: <openSearch:Query role="correction" searchTerms="Bäckerei" totalResults="5256" />
Folgende Elemente sind einem Eintrag im Feed (/feed/entry) untergeordnet und repräsentieren einen gefundenen Datensatz:
| Feld | API-Key erforderlich | Beschrieb |
| /feed/entry/id | nein | Eindeutiger Identifikator gemäss RFC 4287 |
| /feed/entry/published | nein | Publikationsdatum im Timestamp-Format (RFC 3339) Zum Beispiel 2007-01-09T08:00:00Z |
| /feed/entry/updated | nein | Letze Änderung des Eintrags im Timestamp-Format (RFC 3339) Zum Beispiel 2007-01-12T14:32:11Z |
| /feed/entry/title | nein | Titel des Eintrags Name der Person oder Organisation |
| /feed/entry/content | nein | Zusammenfassung des Eintrags in Plaintext |
| /feed/entry/author/name | nein | Autor des Eintrags (gem. RFC 4287) |
| /feed/entry/link/@rel='alternate' | nein | Link zur Detailseite des Eintrags auf tel.search.ch |
| /feed/entry/link/@rel='edit' | nein | Link zur Korrekturseite des Eintrags auf tel.search.ch |
| /feed/entry/link/@type='text/x-vcard' | nein | URL für den Download als VCard |
| /feed/entry/tel:pos | ja | Position des Eintrags im gesamten Resultateset |
| /feed/entry/tel:id | ja | Eindeutige tel.search.ch-ID des Eintrags |
| /feed/entry/tel:type | ja | Art des Eintrags: Person oder Organisation |
| /feed/entry/tel:org | ja | Organisationsname |
| /feed/entry/tel:name | ja | Nachname der Person resp. Name der Firma/Organisation |
| /feed/entry/tel:firstname | ja | Vorname der Person |
| /feed/entry/tel:subname | ja | Namenszusatz |
| /feed/entry/tel:maidenname | ja | Ledigname der Person |
| /feed/entry/tel:occupation | ja | Beruf der Person, Zusatzbezeichnung bei Firmeneinträgen |
| /feed/entry/tel:category | ja | Rubrik bei Firmeneinträgen (mehrere Elemente möglich) |
| /feed/entry/tel:street | ja | Strassenbezeichnung |
| /feed/entry/tel:streetno | ja | Hausnummer |
| /feed/entry/tel:pobox | ja | Postfach |
| /feed/entry/tel:zip | ja | Postleitzahl |
| /feed/entry/tel:city | ja | Ortsbezeichnung |
| /feed/entry/tel:canton | ja | Kantonskürzel (ZH,BE,AG,...) |
| /feed/entry/tel:nopromo | ja | * Wünscht keine Werbung |
| /feed/entry/tel:phone | ja | Telefonnummer mit Ländervorwahl |
| /feed/entry/tel:extra/@type='fax' | ja | Faxnummer (optional) |
| /feed/entry/tel:extra/@type='email' | ja | E-Mail-Adresse (optional) |
| /feed/entry/tel:extra/@type='website' | ja | Website URL (optional) |
| /feed/entry/tel:extra/@type='skype' | ja | Skype-Name (optional) |
| /feed/entry/tel:extra/@type='icq|msn|aim|yahoo' | ja | Instant-Messenger-Name (optional) |
Eine Beispiel-Response im Atom-Format: api-response.xml
Jede Anfrage wird mit einem Status-Code gemäss HTTP-Spezifikation beantwortet. Nachfolgend die häufigsten Status-Codes und deren Bedeutung bei API-Requests.
| Code | Beschrieb |
| 200 OK | Keine Fehler |
| 400 BAD REQUEST 401 | Fehlerhafter Request z.B. fehlende oder ungültige Parameter |
| 403 FORBIDDEN | Authorisation des API-Keys ist fehlgeschlagen |
| 404 NOT FOUND | Kein API-Feed unter dieser URL |
Bei fehlgeschlagener Authorisation des API-Keys wird zusätzlich im Body eine Beschreibung des Problems in Form eines Atom-Feeds mit spezifischen Feldern angegeben:
| Code | Beschrieb |
| /feed/tel:errorCode | Fehlercode |
| /feed/tel:errorReason | Grund des Fehlers |
| /feed/tel:errorMessage | Beschreibung des Fehlers |
Eine Beispiel-Fehlermeldung im Atom-Format: api-error.xml