API

The MIDAS website includes a RESTful API that allows you to query and download sample metadata programmatically. This page explains how to use the API and describes the data that may be retrieved.

Please note that the server keeps a detailed audit log of all requests to the API.

Authentication

When you were given an account on the MIDAS website, you will have been provided with a username, password and API key. The API key is used to authenticate requests to the RESTful API. Every request to the API must have an Authorization header, which gives your username and API key. The required format is <username>:<API key>:

$ curl -i -H "Authorization: jtate:Fj8Iwkfd36oI032gfj2982sze8oPje4U" \
  -H "Accept: application/json" https://www.midasuk.org/summary
HTTP/1.0 200 OK
Date: Mon, 29 Jun 2015 13:05:13 GMT
Content-Type: application/json
Content-Length: 1487

{"submitted_by":{"UCL":"856","CAMBRIDGE":"902","OXFORD":"893"},"total_number_of_manifests":44,"total_numb
...

If you don't provide the Authorization header you will receive a 401 Unauthorized response:

$ curl -i -H "Accept: application/json" https://www.midasuk.org/summary
HTTP/1.0 401 Unauthorized
Date: Mon, 29 Jun 2015 13:15:16 GMT
Content-Length: 62

Must supply username and API key in the "Authorization" header

If you give an invalid or incorrect username or key, you will also receive a 401 Unauthorized response:

$ curl -i -H "Accept: application/json" -H "Authorization: bad#user: " https://www.midasuk.org/summary
HTTP/1.0 401 Unauthorized
Date: Mon, 29 Jun 2015 13:24:18 GMT
Content-Length: 60

Malformed "Authorization" header; must be "username:api_key"

Formats

The API can return data in several formats: text/csv, application/json, and text/yaml. Note that some endpoints, notably the sample summary, will not return data in CSV format, because the output can't easily be converted to a simple tabular format.

You can specify the format that you want in two ways, using the Accept header:

$ curl -i -H "Authorization: jtate:$API_KEY" -H "Accept: application/json" https://www.midasuk.org/summary
HTTP/1.0 200 OK
Date: Mon, 29 Jun 2015 13:05:43 GMT
Content-Type: application/json
Content-Length: 1487

{"submitted_by":{"UCL":"856","CAMBRIDGE":"902","OXFORD":"893"},"total_number_of_manifests":44,"total_numb
...

Or using a URL parameter:

$ curl -i -H "Authorization: jtate:$API_KEY" "https://www.midasuk.org/summary?content-type=text/yaml"
HTTP/1.0 200 OK
Date: Tue, 30 Jun 2015 08:30:41 GMT
Content-Type: text/yaml; charset=UTF-8
Content-Length: 1480

---
submitted_by:
  CAMBRIDGE: 902
  OXFORD: 893
  UCL: 856
compound_counts:
  ampicillin:
    R: 20
    S: 18
  ciprofloxacin:
    R: 5
    S: 63
...

If you don't specify a content type, the server will assume that it is returning data to a browser and will format your results as text/html.

Endpoints

Summary

/summary

Retrieves a summary of all of the sample metadata currently available

Results

The sections in the response are:

submitted_by
the number of samples collected at each of the HICF member institutions
total_number_of_manifests
the number of sample manifests that have been loaded
total_number_of_samples
the total number of samples that have been loaded
scientific_names
the scientific names and number of samples collected from sampled organisms
scientific_names
the number of samples collected from each organism
sir_counts
the number of samples which have antimicrobial resistance test results showing susceptibility (S), intermediate susceptibility (I), or resistance (R) to one or more antimicrobials
compound_counts
the number of samples exhibiting susceptibility, intermediate susceptibility, or resistance to the specified antimicrobial

Example output

{
  "submitted_by": {
    "UCL": "856",
    "CAMBRIDGE": "902",
    "OXFORD": "893"
  },
  "total_number_of_manifests": 44,
  "total_number_of_samples": 12066,
  "scientific_names": {
    "Pseudomonas aeruginosa": "105",
    "mixed culture": "542",
    "H1N2 subtype": "450",
    "Mycobacterium tuberculosis": "341",
    "Influenzavirus A": "781",
    "H1N1 subtype": "91",
    "Mycobacterium abscessus": "154",
    "unidentified influenza virus": "304",
    "Mycobacterium xenopi": "305",
    "Enterococcus faecalis": "231",
    "Mycobacterium gordonae": "40"
  },
  "sir_counts": {
    "R": "6054",
    "I": "355",
    "S": "4690"
  },
  "compound_counts": {
    "streptomycin": {
      "R": "41",
      "S": "122"
    },
    "teicoplanin": {
      "S": "95",
      "R": "42"
    },
    "gentamicin": {
      "R": "58",
      "S": "68"
    },
    "ampicillin": {
      "R": "2",
      "S": "28"
    },
    "erythromycin": {
      "R": "96",
      "I": "25",
      "S": "9"
    },
    "tetracycline": {
      "R": "23",
      "S": "13"
    },
    "vancomycin": {
      "R": "62",
      "S": "68"
    },
    "clindamycin": {
      "R": "34",
      "S": "2"
    },
    "ciprofloxacin": {
      "S": "36",
      "R": "58"
    }
  }
}

All samples

/samples

Retrieves metadata for all samples in the database

Results

The returned metadata fields are described in the manifest template and the HICF checklist. Results are ordered by ascending sample ID.

Results may be filtered by adding one or more filter parameters to the URL, e.g.

$ curl -i -H "Authorization: jtate:Fj8Iwkfd36oI032gfj2982sze8oPje4U" \
  -H "Accept: application/json" 'https://www.midasuk.org/samples?filter=avium&filter=2013'
HTTP/1.0 200 OK
Date: Mon, 29 Jun 2015 13:24:20 GMT
Content-Type: application/json
Content-Length: 3312

[{"host_associated":"yes","amr":[],"other_classification":null,"specific_host":"Homo sapiens","sample_id
...

Example output

[
  {
    "host_associated": "yes",
    "source": null,
    "sample_description": null,
    "other_classification": null,
    "sample_id": "155",
    "sample_accession": "0",
    "host_isolation_source": "BTO:0000155",
    "host_disease_status": "diseased",
    "scientific_name": "unidentified influenza virus",
    "amr": [],
    "raw_data_accession": "4543s.fas",
    "location": "London",
    "tax_id": "11309",
    "patient_location": "inpatient",
    "specific_host": "Homo sapiens",
    "submitted_by": "CAMBRIDGE",
    "manifest_id": "A465A9E0-09FD-11E5-A371-14A80E07C9D0",
    "serovar": "not available: not collected",
    "isolate": null,
    "collection_date": "2014-10-25",
    "collected_by": "not available: not collected",
    "strain": null,
    "isolation_source": null
  },
  {
    "patient_location": "inpatient",
    "specific_host": "Homo sapiens",
    "submitted_by": "CAMBRIDGE",
    "tax_id": "11309",
    "location": "London",
    "raw_data_accession": "4543s.fas",
    "scientific_name": "unidentified influenza virus",
    "amr": [],
    "collected_by": "not available: not collected",
    "isolation_source": null,
    "strain": null,
    "isolate": null,
...

/samples/<start>/<num>

Retrieves metadata for a subset of samples

Arguments

  • start — first row to return
  • num — number of rows to return

Both <start> and <num> must be ≥ 1.

Results

The returned metadata fields are identical to those returned by /samples, as described in the manifest template and the HICF checklist. Results are ordered by ascending sample ID.

Single sample

/sample/<sample ID>

Retrieves metadata for a single sample

Arguments

  • sample ID — the ID of the sample to be returned

Results

The returned metadata fields are described in the manifest template and the HICF checklist.

Example output

{
  "sample_accession": "B23546",
  "other_classification": null,
  "specific_host": "Homo sapiens",
  "source": null,
  "collected_by": null,
  "amr": [
    {
      "method": null,
      "created_at": "2015-06-10 09:10:40",
      "antimicrobial_name": "ampicillin",
      "equality": "ge",
      "deleted_at": null,
      "mic": "20",
      "sample_id": "1",
      "susceptibility": "R"
    },
    {
      "sample_id": "1",
      "mic": "12",
      "susceptibility": "S",
      "method": null,
      "created_at": "2015-06-10 09:10:40",
      "antimicrobial_name": "erythromycin",
      "equality": "eq",
      "deleted_at": null
    },
    {
      "sample_id": "1",
      "mic": "500",
      "susceptibility": "R",
      "created_at": "2015-06-10 09:10:40",
      "method": null,
      "equality": "ge",
      "deleted_at": null,
      "antimicrobial_name": "streptomycin"
    },
    {
      "method": null,
      "created_at": "2015-06-10 09:10:40",
      "antimicrobial_name": "tetracycline",
      "equality": "le",
      "deleted_at": null,
      "sample_id": "1",
      "mic": "10",
      "susceptibility": "S"
    },
    {
      "mic": "10",
      "sample_id": "1",
      "susceptibility": "R",
      "method": null,
      "created_at": "2015-06-10 09:10:40",
      "antimicrobial_name": "vancomycin",
      "deleted_at": null,
      "equality": "eq"
    }
  ],
  "host_associated": "yes",
  "sample_description": "WGS of streptococcus",
  "location": "GAZ:00444180",
  "antimicrobial_resistance": "ampicillin;R;ge20,erythromycin;S;12,streptomycin;R;ge500,tetracycline;S;le10,vancomycin;R;eq10",
  "patient_location": "inpatient",
  "scientific_name": "Streptococcus pneumoniae",
  "isolate": null,
  "tax_id": "197911",
  "raw_data_accession": "A00924940",
  "submitted_by": "UCL",
  "strain": "not available; not collected",
  "isolation_source": null,
  "host_disease_status": "carriage",
  "serovar": "not available: not collected",
  "collection_date": "2014-09-12",
  "host_isolation_source": "temporarily obscured"
}

Samples by organism

/samples/<organism>

Returns all samples from the specified organism

Arguments

  • organism — either the scientific name of the organism, e.g. Influenzavirus A, or its NCBI taxonomy ID, e.g. 197911

Results

The returned metadata fields are identical to those returned by /samples, as described in the manifest template and the HICF checklist. Results are ordered by ascending sample ID.

/samples/<organism>/<start>/<num>

Returns a page of samples from the specified organism

Arguments

  • organism — either the scientific name, e.g. Influenzavirus A, or NCBI taxonomy ID, e.g. 197911 of the organism
  • start — the number of the first row to return
  • num — number of rows to return

Results

The returned metadata fields are identical to those returned by /samples, as described in the manifest template and the HICF checklist. Results are ordered by ascending sample ID.

Samples by antimicrobial susceptibility

/samples_with_susceptibility/<susceptibility>

Returns all samples that have antimicrobial resistance test results with the given susceptibility

Arguments

  • susceptibility — either S, I, or R

Results

The returned metadata fields are identical to those returned by /samples, as described in the manifest template and the HICF checklist. Results are ordered by ascending sample ID.

/samples_by_antimicrobial/<name>/<?susceptibility>

Retrieves samples that have antimicrobial resistance test results against the specified antimicrobial and with the given susceptibility

Arguments

  • name — antimicrobial compound name
  • susceptibility — either S, I, or R. Optional

If <susceptibility> is not given, the API will return all samples that have antimicrobial resistance test results against the specified compound, regardless of the organism's susceptibility to the compound.

Results

The returned metadata fields are identical to those returned by /samples, as described in the manifest template and the HICF checklist. Results are ordered by ascending sample ID.

Bulk searching

/search

Uploads a CSV file defining a set of searches and returns metadata for matching samples, also in CSV format. See Search documentation (must be signed in).

Arguments

  • query — file upload

Results

The returned metadata fields are the same as those returned by /samples, but the only available format is CSV.

Example input

submitted_by,collected_after,collected_before
CAMBRIDGE,2013-10-01,2014-06-01

Example output

sample_id,manifest_id,raw_data_accession,sample_accession,donor_id,sample_description,submitted_by,tax_id,scientific_name,collected_by,source,collection_date,location,host_associated,specific_host,host_disease_status,host_isolation_source,patient_location,isolation_source,serovar,other_classification,strain,isolate,amr,query_number
12332,8879DC0F-9AB4-443E-9A90-D8EF8892A20B,SRR1735577,SAMN02995393,D00554664,"Whole genome sequencing of mycobacteria",OXFORD,1764,"Mycobacterium abscessus",,,2012-14-10,GAZ:00456742,yes,"Homo sapiens",carriage,BTO:001297,inpatient,,"not available: not collected","not available: not collected",F54667,,,1
12332,8879DC0F-9AB4-443E-9A90-D8EF8892A20B,SRR1735509,SAMN02995363,D00054336,"Whole genome sequencing of mycobacteria",OXFORD,1764,"Mycobacterium abscessus",,,2012-14-06,GAZ:00567427,yes,"Homo sapiens",carriage,BTO:001297,inpatient,,"not available: not collected","not available: not collected",F54667,,,1
...