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 query service endpoint
| v2: | http://mygene.info/v2/query |
|---|---|
| v3: | http://mygene.info/v3/query |
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
"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
"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".
"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
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