search.ch
  1. Queries
  2. Response-Format
  3. HTTP Status Codes
  4. Neuen API Schlüssel anfordern
  5. Nutzungsbedingungen

API Spezifikation

Queries

Anfragen werden als HTTP-URIs ans API gesendet. Dies entspricht dem Konzept von REST.

Das Produkt sowie die Nutzungsbestimmungen werden aktuell überarbeitet.

Wenn Sie einen API-Schlüssel bestellen, können Sie mehr Anfragen pro Tag machen.

https://tel.search.ch/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.

ParameterOptionalBeschrieb
wasneinAllgemeiner Suchstring. Suche nach Namen, Rubriken oder Telefonnummern
wojaGeografische Einschränkung der Suche.
Dies kann eine Strasse, Ortsbezeichnung, Postleitzahl oder ein Kantonskürzel sein.
qjaFür Einfeldsuche. Die Begriffe werden in was und wo gesucht.
privatja1 = Suche in Privateinträgen, 0 = Privateinträge werden ausgeschlossen. Default = 1
firmaja1 = Suche in Firmeneinträgen, 0 = Firmeneinträge werden ausgeschlossen. Default = 1
posjaPosition des ersten Eintrags in der Abfrage.
Wird bei Anfragen mit mehr Resultaten als maxnum verwendet.
maxnumjaAnzahl Resultate im Feed.
Die Ausgabe ist aber auf maximal 200 Einträge beschränkt.
keyjaAPI-Key. Einen Schlüssel können Sie über unser Formular anfordern.
langjaAusgabesprache. Mögliche Werte: de,fr,it,en
Übersetzbare Informationen wie z.B. Kategorien werden in der angegebenen Sprache ausgegeben.
count_onlyja1 = nur die Zahl der Resultate liefern (schneller)

Response-Format

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:

openSearch:totalResults
Total gefundene Einträge
openSearch:startIndex
Position des ersten Eintrags im Resultate-Set. Start bei 1
openSearch:itemsPerPage
Anzahl angezeigter Einträge im Feed. Dies enspricht dem Parameter maxnum.
openSearch:Query
Die Repräsentation der aktuellen Suchanfrage.
Form: <openSearch:Query role="request" searchTerms="..." startPage="1" />

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:

FeldAPI-Key erforderlichBeschrieb
/feed/entry/idneinEindeutiger Identifikator gemäss RFC 4287
/feed/entry/publishedneinPublikationsdatum im Timestamp-Format (RFC 3339)
Zum Beispiel 2007-01-09T08:00:00Z
/feed/entry/updatedneinLetze Änderung des Eintrags im Timestamp-Format (RFC 3339)
Zum Beispiel 2007-01-12T14:32:11Z
/feed/entry/titlenein Titel des Eintrags
Name der Person oder Organisation
/feed/entry/contentneinZusammenfassung des Eintrags in Plaintext
/feed/entry/author/nameneinAutor des Eintrags (gem. RFC 4287)
/feed/entry/link/@rel='alternate'neinLink zur Detailseite des Eintrags auf tel.search.ch
/feed/entry/link/@rel='edit'neinLink zur Korrekturseite des Eintrags auf tel.search.ch
/feed/entry/link/@type='text/x-vcard'neinURL für den Download als VCard
/feed/entry/tel:posjaPosition des Eintrags im gesamten Resultateset
/feed/entry/tel:idjaEindeutige tel.search.ch-ID des Eintrags
/feed/entry/tel:typejaArt des Eintrags: Person oder Organisation
/feed/entry/tel:orgjaOrganisationsname
/feed/entry/tel:namejaNachname der Person resp. Name der Firma/Organisation
/feed/entry/tel:firstnamejaVorname der Person
/feed/entry/tel:subnamejaNamenszusatz
/feed/entry/tel:maidennamejaMädchenname der Person
/feed/entry/tel:occupationjaBeruf der Person, Zusatzbezeichnung bei Firmeneinträgen
/feed/entry/tel:categoryjaRubrik bei Firmeneinträgen (mehrere Elemente möglich)
/feed/entry/tel:streetjaStrassenbezeichnung
/feed/entry/tel:streetnojaHausnummer
/feed/entry/tel:poboxjaPostfach
/feed/entry/tel:zipjaPostleitzahl
/feed/entry/tel:cityjaOrtsbezeichnung
/feed/entry/tel:cantonjaKantonskürzel (ZH,BE,AG,...)
/feed/entry/tel:nopromoja* Wünscht keine Werbung
/feed/entry/tel:phonejaTelefonnummer mit Ländervorwahl
/feed/entry/tel:extra/@type='fax'jaFaxnummer (optional)
/feed/entry/tel:extra/@type='email'jaE-Mail-Adresse (optional)
/feed/entry/tel:extra/@type='website'jaWebsite URL (optional)
/feed/entry/tel:extra/@type='skype'jaSkype-Name (optional)
/feed/entry/tel:extra/@type='icq|msn|aim|yahoo'jaInstant-Messenger-Name (optional)

Eine Beispiel-Response im Atom-Format: api-response.xml

HTTP Status Codes

Jede Anfrage wird mit einem Status-Code gemäss HTTP-Spezifikation beantwortet. Nachfolgend die häufigsten Status-Codes und deren Bedeutung bei API-Requests.

CodeBeschrieb
200 OKKeine Fehler
400 BAD REQUEST
401
Fehlerhafter Request
z.B. fehlende oder ungültige Parameter
403 FORBIDDENAuthorisation des API-Keys ist fehlgeschlagen
404 NOT FOUNDKein 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:

CodeBeschrieb
/feed/tel:errorCodeFehlercode
/feed/tel:errorReasonGrund des Fehlers
/feed/tel:errorMessageBeschreibung des Fehlers

Eine Beispiel-Fehlermeldung im Atom-Format: api-error.xml