samedi API Reference

Search API

Table of contents

  1. Introduction
  2. Institution Search
  3. Institution’s Details
  4. Healthcare Professionals Search
  5. Getting doctor by id

Introduction

The samedi® Search API allows integrators to search for samedi-powered institutions (medical practices, clinics, hospitals, etc.). The API consists of two endpoints: the Institution Search and the Healthcare Professional Search.

All communication is performed over the HTTPS protocol. All data interchanged via this API are formatted as JSON. Access to the Search API requires a set of valid credentials (see below).

Obtaining your API Credentials

The Search API requires an api_key as parameter in every request.

You can obtain your unique key by registering yourself in the Search API signup page. Please not that a valid email address is required to complete your registration.

After confirming your email address please allow up to 2 working days for our support team to review and activate your credentials.

Please do not share or reveal your api_key in user-facing code (e.g. frontend code).

In order to perform a search across samedi-powered institutions you need to make a request to the following endpoint with any of the following parameters.

GET https://app.samedi.de/api/search/v2/institutions?api_key=your_api_key
Name Value
Format		 Default Description
q string Full-text search string, e.g. “Mustermann.”
near string Currently supports German addresses only.
Place names or complete, five-digit postal codes. Examples: “Hamburg”, “Rigaer Str. 44, Berlin” or “10247”
If a clear assignment is not possible (e.g. searching for “Neustadt” would yield many different results), the first result will be used as the basis of the search.
In these cases, attention must be paid to a clear identification by additives (e. g. “Neustadt an der Dosse”) in order to obtain the desired result. The API does not provide feedback if there are multiple results.
radius string 500km Only useful in combination with the parameter “near”.
Please note that the unit km has to be included in the passed value
Examples for valid values: 5km, 25km, …
field string Area of Expertise

The available subject areas can be requested via the following URL: https://app.samedi.de/fields Doesn’t require any authorization. The result is returned as a JSON array. You can use this data to provide a select field for your user.
The Search API expects one field from that list as a string.
tags string List of tags for filtering. See “Filtering results by tags parameter” section below.
appointment_type_tags string List of appointment type tags used to filter institutions that contain a given tag on an appointment type. See the “Filtering results by appointment type tags parameter” section below.
has_video_consultations boolean Filter institutions that offer video consultation appointments. For a value true all institutions that offer at least 1 video consultation appointment, it will be returned together with all their video and non-video consultation appointments. To display only video consultation appointments, check the is_video_consultation attribute in the event_types array.
page integer 1 Pagination parameter
per_page integer 10 Pagination parameter

Response:

Except of the basic institution details, such as id, name, street, etc. we also return 3 arrays: * healers - all healthcare providers of an institution, with a category healer and their event_types. * event_types - all event types which do not belong to a healer category, i.e. events from custom categories. In the example below, General medicine is a custom category and there might be more than 1 healer linked to it. * institution_categories - same data shown in event_types, but grouped by category.

{
   "root":[
      {
         "id":"abc123def",
         "name":"Koch & Koch",
         "street":"Voigtstraße 35",
         "zip":"10247",
         "city":"Berlin",
         "url":null,
         "fax":"+49 30 - 212307079",
         "phone":"+49 30 - 212307070",
         "email":null,
         "latitude":52.516571,
         "longitude":13.468206,
         "descriptive_field":"The Surgery",
         "event_types":[
           {
             "name":"Diabetes consultation",
             "categories":[
                "General medicine"
             ],
             "is_video_consultation":false,
             "booking_url":"https://app.samedi.de/...",
             "booking_iphone_url":"https://app.samedi.de/..."
           }
         ],
         "healers":[
            {
               "name":"Prof. Robert Koch",
               "id":"h987654321",
               "photo_url":"https://app.samedi.de/...",
               "title":"Prof.",
               "gender":"male",
               "fields":"Doctor of applied information extraction techniques",
               "event_types":[
                  {
                     "name":"Specific Consultation",
                     "categories":[
                        "Prof. Koch, Robert"
                     ],
                     "is_video_consultation":false,
                     "booking_url":"https://app.samedi.de/..."
                  },
                  {
                     "name":"General Consultation",
                     "categories":[
                        "Prof. Koch, Robert",
                        "General"
                     ],
                     "is_video_consultation":false,
                     "booking_url":"https://app.samedi.de/..."
                  },
                  {
                     "name":"Private Consultation",
                     "categories":[
                        "Prof. Koch, Robert"
                     ],
                     "is_video_consultation":false,
                     "booking_url":"https://app.samedi.de/..."
                  }
               ]
            }
         ],
         "institution_categories": [
           {
              "name":"General medicine",
              "id":"5",
              "event_types":[
                {
                  "name":"Diabetes consultation",
                  "is_video_consultation":false,
                  "booking_url":"https://app.samedi.de/..."
                }
              ]
           }
         ],
         "samedi_homepage":"https://app.samedi.de/...",
         "photo_url":null,
         "opening_hours":"Mo-Fr: 8-18",
         "distance":null,
         "has_online_booking":true,
         "has_video_consultations":false
      },
      {
         "id":"shaw",
         "name":"Shaw & Partner",
         "street":"Bernauer Str. 55",
         "zip":"10115",
         "city":"Berlin",
         "url":null,
         "fax":"+49 30 - 567789079",
         "phone":"+49 30 - 567789070",
         "email":null,
         "latitude":52.5380289,
         "longitude":13.3953847,
         "descriptive_field":"The surgery2",
         "event_types":[
         ],
         "healers":[
            {
               "name":"Dr. med. Heribert Shaw",
               "id":"hshaw",
               "photo_url":"https://app.samedi.de/...",
               "title":"Dr. med.",
               "gender":"male",
               "fields":"HNO",
               "event_types":[
                  {
                     "name":"Acupunture",
                     "categories":[
                        "Dr. med. Shaw, Heribert"
                     ],
                     "is_video_consultation":false,
                     "booking_url":"https://app.samedi.de/..."
                  },
                  {
                     "name":"Video Consultation",
                     "categories":[
                        "Dr. med. Shaw, Heribert"
                     ],
                     "is_video_consultation":true,
                     "booking_url":"https://app.samedi.de/..."
                  }
               ]
            }
         ],
          "institution_categories": [
          ],
         "samedi_homepage":"https://app.samedi.de/...",
         "photo_url":null,
         "opening_hours":"Mo-Fr: 8-18",
         "distance":null,
         "has_online_booking":true,
         "has_video_consultations":true
      },
      ...
   ],
   "total":13,
   "page":1,
   "per_page":10
}

Institution’s Details

If you already have the institution’s unique identifier and want to retrieve more information, you can do so with the following endpoint:

GET https://app.samedi.de/api/search/v2/institutions/abc123def?api_key=your_api_key

You can find the institution identifier as part of the the search request results.

Response:

The same explanation of the Institution’s Details response applies here as well.

{
   "root":[
      {
         "id":"abc123def",
         "name":"Koch & Koch",
         "street":"Voigtstraße 35",
         "zip":"10247",
         "city":"Berlin",
         "url":null,
         "fax":"+49 30 - 212307079",
         "phone":"+49 30 - 212307070",
         "email":null,
         "latitude":52.5165707,
         "longitude":13.4682055,
         "descriptive_field":"General surgery",
         "event_types":[
         ],
         "healers":[
            {
               "name":"Prof. Robert Koch",
               "id":"h987654321",
               "photo_url":"https://app.samedi.de/...",
               "title":"Prof.",
               "gender":"male",
               "fields":"Doctor of applied information extraction techniques",
               "event_types":[
                  {
                     "name":"Video Consultation",
                     "categories":[
                        "Prof. Koch, Robert"
                     ],
                     "is_video_consultation":true,
                     "booking_url":"https://app.samedi.de/..."
                  },
                  {
                     "name":"General Consultation",
                     "categories":[
                        "Prof. Koch, Robert",
                        "General"
                     ],
                     "is_video_consultation":false,
                     "booking_url":"https://app.samedi.de/..."
                  },
                  {
                     "name":"Private Consultation",
                     "categories":[
                        "Prof. Koch, Robert",
                        "Privat"
                     ],
                     "is_video_consultation":false,
                     "booking_url":"https://app.samedi.de/..."
                  }
               ]
            }
         ],
         "institution_categories": [
         ],
         "samedi_homepage":"https://app.samedi.de/...",
         "photo_url":null,
         "opening_hours":"Mo-Fr: 8-18",
         "distance":null,
         "has_online_booking":true,
         "has_video_consultations":true
      }
   ]
}

In order to perform a search for individual healthcare professionals you need to make a request to the following endpoint with any of the following parameters.

GET https://app.samedi.de/api/search/v2/healers?api_key=your_api_key

Parameters:

All parameters available for the Institution Search can be used with this endpoint as well.

Response:

{
   "root":[
      {
         "id":4,
         "hashed_id":"hshaw",
         "name":"Dr. med. Heribert Shaw",
         "first_name":"Heribert",
         "last_name":"Shaw",
         "city":null,
         "zip":null,
         "street":null,
         "country":null,
         "url":null,
         "fax":null,
         "phone":null,
         "latitude":null,
         "longitude":null,
         "photo_url":null,
         "title":"Dr. med.",
         "description":"",
         "gender":"male",
         "fields":"HNO",
         "event_types":[
            {
               "id":"5",
               "name":"Acupunture",
               "description":"",
               "categories":"Dr. med. Shaw, Heribert",
               "category_id":4,
               "booking_url":"https://app.samedi.de/..."
            },
            {
               "id":"4",
               "name":"General Consultation",
               "description":"",
               "categories":"Dr. med. Shaw, Heribert",
               "category_id":4,
               "booking_url":"https://app.samedi.de..."
            }
         ],
         "practice_id":"shaw",
         "practice_name":"Shaw & Partner",
         "booking_url":"https://app.samedi.de/...",
         "booking_widgets":[
         ],
         "samedi_homepage":"https://app.samedi.de/...",
         "email":null,
         "opening_hours":"Mo-Fr: 8-18",
         "distance":null,
         "external_booking_url":null
      },
      ...
   ],
   "total":13,
   "page":1,
   "per_page":10
}

Getting doctor by id

GET https://app.samedi.de/api/search/v2/healers/abc123def?api_key=your_api_key

replace “abc123def” with doctor id. You get doctor id for every record in the result of the search request.

Response:

{
   "root":[
      {
         "id":4,
         "hashed_id":"abc123def",
         "name":"Dr. med. Max Mustermann",
         "first_name":"Mustermann",
         "last_name":"Max",
         "city":"Berlin",
         "zip":"10279",
         "street":null,
         "country":null,
         "url":null,
         "fax":null,
         "phone":null,
         "latitude":null,
         "longitude":null,
         "photo_url":null,
         "title":"Dr. med.",
         "description":"",
         "gender":"male",
         "fields":null,
         "event_types":[
            {
               "id":"5",
               "name":"Acupuncture",
               "description":"",
               "categories":"Dr. med. Max Mustermann",
               "category_id":4,
               "booking_url":"https://app.samedi.de/..."
            },
            {
               "id":"4",
               "name":"General Consultation",
               "description":"",
               "categories":"Dr. med. Max Mustermann",
               "category_id":4,
               "booking_url":"https://app.samedi.de/..."
            }
         ],
         "practice_id":"shaw",
         "practice_name":"Shaw & Partner",
         "booking_url":"https://app.samedi.de/...",
         "booking_widgets":[
         ],
         "samedi_homepage":"https://app.samedi.de/....",
         "email":null,
         "opening_hours":"Mo-Fr: 8-18",
         "distance":null,
         "external_booking_url":null
      }
   ]
}

Filtering results by tags parameter

Both healers and institutions can have key-value tags. For example institutions can be tagged with “wheelchair_accessible: true”, “elevator: yes”, etc., and healer can be tagged with “language: english, german”, “privat_only: yes”, etc.

Additionally to other parameters you can also specify tags parameter to apply filters for your results.

Examples of url queries with tags:

  1. ?tags[language]=english - will filter the results to only those, that are tagged with tag language with value english.
  2. ?tags[elevator]=yes&tags[ramp]=yes - will filter the results to only those, that are tagged with both elevator: yes AND ramp: yes.
  3. ?tags[elevator]=&tags[ramp]= - alternatively you can skip the value. Then the API returns you all the records, that are tagged with elevator, that can have any not empty value.
  4. ?tags[language][]=english&tags[language][]=russian - this will return only those records, that are tagged with language with value english OR russian

Notice, that, the tag key has to be unique:

?tags[language]=english&tags[language]=russian

will still be accepted by API, but one of the language tag parameters will be ignored. For “OR” request use the syntax described in example 4 above.

The tags can be added to other params like this: ?q=physiotherapie&near=Berlin&radius=10km&tags[elevator]=&tags[ramp]=

Filtering results by appointment type tags parameter

Similar usage as the tags example above, but this will query for institutions where its categories or healers got tagged with the key and value you are querying.

So, the appointment_type_tags query parameter is related to a tag on the event_types objects, inside the healers and institution_categories arrays.

{
    "root": [
        {
            "city": "Berlin",
            "descriptive_field": "The Surgery",
            "event_types": [
                {
                    "booking_iphone_url": "https://app.samedi.de/...",
                    "booking_url": "https://app.samedi.de/...",
                    "categories": [
                        "General medicine"
                    ],
                    "is_video_consultation": false,
                    "name": "Diabetes consultation"
                }
            ],
            "has_video_consultations": false,
            "healers": [
                {
                    "event_types": [
                        {
                            "booking_url": "https://app.samedi.de/...",
                            "categories": [
                                "Prof. Koch, Robert"
                            ],
                            "is_video_consultation": false,
                            "name": "Specific Consultation",
                            "tags": [
                                {
                                    "key": "Specific-Key",
                                    "value": "true"
                                }
                            ]
                        }
                    ],
                    "fields": "Doctor of applied information extraction techniques",
                    "id": "h987654321",
                    "name": "Prof. Robert Koch"
                }
            ],
            "institution_categories": [
                {
                    "event_types": [
                        {
                            "booking_url": "https://app.samedi.de/...",
                            "is_video_consultation": false,
                            "name": "Diabetes consultation",
                            "tags": [
                                {
                                    "key": "Diabetessprechstunde",
                                    "value": "true"
                                }
                            ]
                        }
                    ],
                    "id": "5",
                    "name": "General medicine"
                }
            ],
            "name": "Koch & Koch",
            "samedi_homepage": "https://app.samedi.de/...",
            "zip": "10247"
        }
    ]
}