Migration from v2 API

Migrating from v2 API to v3 API is easy. Here’s a summary of the changes. You may also want to read our blog for complementary information.

URL change

You will need to access v3 API using “/v3” prefix for service urls:

Gene annotation service endpoint

v2

http://mygene.info/v2/gene

v3

http://mygene.info/v3/gene

Returned Objects

There are several small changes in the returned data structure, as summarized here:

Accession number with version

“refseq” and “accession” fields now contain accession number including version. Data can be search with and without version. Version is available for “genomic”, “rna” and “protein” accession number keys.

Note

“genomic” field is returned but is not searchable

v2: http://mygene.info/v2/query?q=NM_052827&fields=refseq.rna

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
  "hits": [
  {
    "_id": "1017",
    "refseq": {
      "rna": [
        "NM_001290230",
        "NM_001798",
        "NM_052827",
        "XM_011537732"
      ]
    }
  }
],
  "max_score": 0.51962745,
  "took": 3,
  "total": 1

}

v3: http://mygene.info/v3/query?q=NM_052827&fields=refseq.rna

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
  "hits": [
    {
      "_id": "1017",
      "_score": 10.052136,
      "refseq": {
        "rna": [
          "NM_001290230.1",
          "NM_001798.4",
          "NM_052827.3",
          "XM_011537732.1"
        ]
      }
    }
  ],
  "total": 1,
  "took": 14,
  "max_score": 10.052136
}

“translation” field for RNA-protein mapping

For “ensembl”, “refseq” and “accession” fields, a new sub-field name “translation” is now available. It gives the association between RNA and its protein product. v2 does not have this information in returned objects.

v3: http://mygene.info/v3/query?q=NM_052827&fields=refseq.translation,refseq.rna,refseq.protein

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
{
  "max_score": 10.052136,
  "total": 1,
  "hits": [
    {
      "_id": "1017",
      "_score": 10.052136,
      "refseq": {
        "protein": [
          "NP_001277159.1",
          "NP_001789.2",
          "NP_439892.2",
          "XP_011536034.1"
        ],
        "rna": [
          "NM_001290230.1",
          "NM_001798.4",
          "NM_052827.3",
          "XM_011537732.1"
        ],
        "translation": [
          {
            "protein": "XP_011536034.1",
            "rna": "XM_011537732.1"
          },
          {
            "protein": "NP_001789.2",
            "rna": "NM_001798.4"
          },
          {
            "protein": "NP_439892.2",
            "rna": "NM_052827.3"
          },
          {
            "protein": "NP_001277159.1",
            "rna": "NM_001290230.1"
          }
        ]
      }
    }
  ],
  "took": 4
}

“exons” data structure modification

Warning

Backward-incompatible, data structure changed

“exons” field has two major modifications. It now contains a list of dictionary instead of a dictionary indexed by the accession number. This accession number is found within the dictionary under the key “transcript”. Finally, inner “exons” key has been rename to “position”.

v2: http://mygene.info/v2/gene/1698?fields=exons

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "_id": "259236",
  "exons": {
    "NM_147196": {
      "cdsstart": 46701487,
      "cdsend": 46709688,
      "txstart": 46701332,
      "txend": 46710923,
      "chr": "3",
      "exons": [
        [
          46701332,
          46701580
        ],
        [
          46705789,
          46705907
        ],
        [
          46709125,
          46709275
        ],
        [
          46709578,
          46710923
        ]
      ],
      "strand": 1
    }
  }


}

v3: http://mygene.info/v3/gene/1698?fields=exons

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "_id": "259236",
  "_score": 21.732534,
  "exons": [
    {
      "cdsend": 46709688,
      "cdsstart": 46701487,
      "chr": "3",
      "position": [
        [
          46701332,
          46701580
        ],
        [
          46705789,
          46705907
        ],
        [
          46709125,
          46709275
        ],
        [
          46709578,
          46710923
        ]
      ],
      "strand": 1,
      "transcript": "NM_147196",
      "txend": 46710923,
      "txstart": 46701332
    }
  ]
}

“dotfield” notation default changed

Warning

May be backward-incompatible, default data structure changed (but can be restored with “dotfield” paramater setting)

By default, “dotfield” notation is now disabled for gene annotation endpoint in v3 (/gene). It’s enabled by default in v2. You will need to explicitely pass “dotfield=1” to your queries to have the same behavior as v2.

Note

“dotfield” notation is disabled by default for gene query endpoint (/gene) in both v2 and v2

v2: http://mygene.info/v2/gene/1017?fields=refseq.rna

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{

  "_id": "1017",
  "refseq.rna": [
    "NM_001290230",
    "NM_001798",
    "NM_052827",
    "XM_011537732"
  ]


}

v3: http://mygene.info/v3/gene/1017?fields=refseq.rna

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "_id": "1017",
  "_score": 21.731894,
  "refseq": {
    "rna": [
      "NM_001290230.1",
      "NM_001798.4",
      "NM_052827.3",
      "XM_011537732.1"
    ]
  }
}

Querying “reporter” data source

“reporter” data now has to be queried explicitelty, prefixing the query term by “reporter:”

v3: http://mygene.info/v3/query?q=reporter:2845421&fields=reporter