search.ch
  1. Queries
  2. Response Format
  3. HTTP status codes
  4. Request for a new API key
  5. Terms of Use

API Specification

Queries

Requests are sent to the API as HTTP-URIs, according to the concept of REST.

The product and the terms of use are currently being revised.

If you obtain a key, you can make more queries per day.

http://tel.search.ch/api/?was=john+meier&key=Your key

A normal and correct request is answered by status HTTP 200. Invalid requests or requests with an invalid API key will get the apropriate HTTP statuscode as a response.

The following parameters are possible in the request. All values must be urlencoded.

ParameterOptionalDescription
wasnoGeneral searchstring. Search for names, categories or phone numbers
woyesRefine you search geographically.
It can contain the name of a street or a city, a npa or an abbreviation of a canton.
qyesFor single-field queries. The words will be searched in was and wo.
privatyes1 = Search for private entries, 0 = Exclude private entries. Default = 1
firmayes1 = Search for a business, 0 = Exclude business entries. Default = 1
posyesPosition of the first entry in the query.
Used for queries with more than maxnum results.
maxnumyesNumber of results in the feed.
The output is limited to 200 entries.
keyyesAPI-key. Use our online form to request your own key.
langyesOutput language. Possible values: de,fr,it,en
Translatable information (e.g. categories) are translated into the specified language.
count_onlyyes1 = return result count only (faster)

Format of the response

Results are shown as Atom feeds. The feed complemented with its own namespace for OpenSearch elements and tel.search.ch specific fields.

The following OpenSearch elements are directly subordinated on the element <feed>:

openSearch:totalResults
Total number of found entries
openSearch:startIndex
Position of the first entry in the resultset. Starts with 1
openSearch:itemsPerPage
Number of shown entries in th feed. It corresponds to the parameter maxnum.
openSearch:Query
Represents the actual searchquery.
Syntax: <openSearch:Query role="request" searchTerms="..." startPage="1" />

If no entries are found with the actual searchquery an additional query element is added with suggestions.
Example: <openSearch:Query role="correction" searchTerms="B├Ąckerei" totalResults="5256" />

The following elements are subordinated to an entry in the feed (/feed/entry) and represent a record:

FieldAPI key mandatoryDescription
/feed/entry/idnoUnique identifier according to RFC 4287
/feed/entry/publishednoDate of publication in timestamp syntax (RFC 3339)
E.g. 2007-01-09T08:00:00Z
/feed/entry/updatednoLast change of an entry in timestamp syntax (RFC 3339)
E.g. 2007-01-12T14:32:11Z
/feed/entry/titlenoTitle of the entry
Name of the person or business
/feed/entry/contentnoAbstract of the entry in plaintext
/feed/entry/author/namenoAuthor of the entry (according to RFC 4287)
/feed/entry/link/@rel='alternate'noLink to the detailpage of the entry on tel.search.ch
/feed/entry/link/@rel='edit'noLink to the correctionpage of the entry on tel.search.ch
/feed/entry/link/@type='text/x-vcard'noURL the VCard download
/feed/entry/tel:posyesPosition of the entry according to the whole resultset
/feed/entry/tel:idyesUnique tel.search.ch identification of the entry
/feed/entry/tel:typeyesType of the entry: Person or Organisation
/feed/entry/tel:orgjaOrganization name
/feed/entry/tel:nameyesLastname or the person or business
/feed/entry/tel:subnamejaAdditional name
/feed/entry/tel:firstnameyesFirstname of the person
/feed/entry/tel:maidennameyesMaiden name of the person
/feed/entry/tel:occupationyesOccupation of the person, Additional information for business entries
/feed/entry/tel:categoryyesCategory of the business entry (multiple elements possible)
/feed/entry/tel:streetyesStreet
/feed/entry/tel:streetnoyesNumber
/feed/entry/tel:poboxjaP.O.Box address
/feed/entry/tel:zipjaZIP
/feed/entry/tel:cityjaCity
/feed/entry/tel:cantonjaAbbreviation of canton (ZH,BE,AG,...)
/feed/entry/tel:nopromoja* No promotions please
/feed/entry/tel:phonejaPhone number with area code
/feed/entry/tel:extra/@type='fax'jaFax (optional)
/feed/entry/tel:extra/@type='email'jaE-mail (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 (optional)

An example for a response in Atom syntax: api-response.xml

HTTP status codes

Every request will be answered with a status code according to HTTP specification. The most frequent status codes are listed below including the specific meaning on API requests.

CodeDescription
200 OKNo errors
400 BAD REQUEST
401
Invalid request
e.g. missing or wrong parameters
403 FORBIDDENAuthorisation failed, wrong API key
404 NOT FOUNDNo API feed on this URL

If the authorisation of the API key failed an additional description of the problem is added in the body in Atom feed syntax with dedicated fields:

CodeDescription
/feed/tel:errorCodeErrorcode
/feed/tel:errorReasonCause of the error
/feed/tel:errorMessageDescription of the error

An example of an error message in Atom syntax: api-error.xml