MGI-MGI Web Services

MGI Web Service

Introduction |
Service Requests |
Request Details |
Example Clients

Introduction

The MGI Web Service provides programmatic access to select portions of the database. The following data are currently available:

MGI IDs - You can upload a set of identifiers (e.g. EntrezGene, GenBank, mouse symbol, etc.) and receive a list of the corresponding MGI gene/marker IDs.
Batch Query for Genes/Markers - You can upload a set of identifiers and specify the associated attributes to return. See MGI Batch Query, an interactive tool that mirrors this functionality, for a list of available data attributes.

Please feel free to contact User Support with questions, comments, or suggestions for the MGI Web Service.

Note: The service is unavailable Tuesdays between 5:00AM - 9:00AM ET for database maintenance.

Service Requests

Our web service accepts SOAP requests via the submitDocument method. The body of the SOAP request must contain a single <submitDocument> element that contains one of the following request elements:

<mgiIDRequest>
<batchMarkerRequest>

Contact Information

All requests contain a <requestorEmail> element. The contact information in this element may be used to notify you of invalid requests or requests that place a heavy load on our servers. If you cannot be contacted to resolve these issues, you may have your IP address blocked.

WSDL & Schemas

WSDL - Web Service Definition Language
mgiwsRequests.xsd - Schema for the request elements and corresponding request type definitions.
mgiwsBatchTypes.xsd - Schema for supporting type definitions used to define the <mgiIDRequest> and <batchMarkerRequest> elements.

Request Details

<mgiIDRequest>

The <mgiIDRequest> element lets you upload a set of identifiers and receive the corresponding MGI IDs for all genes/markers annotated to the input identifiers. All identifiers in the request set must be of the same supported type.

The <mgiIDRequest> element is composed of:

<requestorEmail> - The email address of the requestor. This element is defined in the http://ws.mgi.jax.org/xsd/request namespace.

<IDSet> - An optional IDType attribute and 1 or more <id> sub-elements. The <IDSet> element is defined in the http://ws.mgi.jax.org/xsd/request namespace. The optional IDType attribute must be one of the case sensitive strings defined below and is used to indicate what type of identifiers the set contains. If this attribute is omitted auto is assumed and the batchMarkerRequest will attempt to detect type of the input ids it receives. Note that this option supports an IDSet containing ids of mixed type. The <id> sub-elements each contain an individual identifier, and queries for the identifiers are case insensitive. The <id> element is defined in the http://ws.mgi.jax.org/xsd/request namespace.

Currently supported input identifier types:

IDType Examples

auto Any type of IDs may be used.

symbol Pax6

nomen TP53

entrezGene 22173

ensembl ENSMUSG00000029335

vega OTTMUSG00000015006

unigene 181490

mirbase MI0005552

genbankRefseq NM_146146

uniprot P48356

go GO:0019221

refsnp rs27429143

affy1 10344624

affy2 1415680_at

Example #1 request - An example of an <mgiIDRequest> containing 3 current mouse symbols. Note: namespace declarations are required.
    <submitDocument xmlns:req="http://ws.mgi.jax.org/xsd/request"
            xmlns:bt="http://ws.mgi.jax.org/xsd/batchType">
        <req:mgiIDRequest>
            <req:requestorEmail>myid@mydomain.com</req:requestorEmail>
            <req:IDSet IDType="symbol">
                <bt:id>foo</bt:id>
                <bt:id>Trp53</bt:id>
                <bt:id>Pax6</bt:id>
            </req:IDSet>
        </req:mgiIDRequest>
    </submitDocument>
    
Example #1 response - All responses to the <mgiIDRequest> contain the following:

A <summary> element containing data about the web service version, database version, query parameters, and result counts

At least one <row> element per input identifier

An <Input> element to indicate the uploaded input identifier

An <mgiGeneMarkerID> element that contains the matching gene/marker MGI ID corresponding to the input identifier.
    <mgi:submitDocumentResponse xmlns:mgi="http://ws.mgi.jax.org/xsd">
        <mgi:summary>
            <mgi:wsVersion>1.0</mgi:wsVersion>
            <mgi:genomeBuild>36</mgi:genomeBuild>
            <mgi:databaseVersion>MGI 4.01</mgi:databaseVersion>
            <mgi:databaseDate>03/20/2008</mgi:databaseDate>
            <mgi:inputCount>3</mgi:inputCount>
            <mgi:inputType>symbol</mgi:inputType>
            <mgi:resultCount>3</mgi:resultCount>
            <mgi:returnCount>3</mgi:returnCount>
        </mgi:summary>
        <mgi:row>
            <mgi:Input>foo</mgi:Input>
            <mgi:inputtype>Unknown</mgi:inputtype>
            <mgi:mgiGeneMarkerID />
        </mgi:row>
        <mgi:row>
            <mgi:Input>Trp53</mgi:Input>
            <mgi:inputtype>current symbol</mgi:inputtype>
            <mgi:mgiGeneMarkerID>MGI:98834</mgi:mgiGeneMarkerID>
        </mgi:row>
        <mgi:row>
            <mgi:Input>Pax6</mgi:Input>
            <mgi:inputtype>current symbol</mgi:inputtype>
            <mgi:mgiGeneMarkerID>MGI:97490</mgi:mgiGeneMarkerID>
        </mgi:row>
    </mgi:submitDocumentResponse>
    
Results & Limits

Empty elements in the result set indicate that there is no match to a gene/marker. For example, any input identifier that cannot be matched by the designated IDType, or that has no gene/marker association within MGI, is returned with an empty <mgiGeneMarkerID> element.

The number of <row> elements returned appears in the <returnCount> element within the <summary> element. Results are currently limited to 20,000 <row> elements.

The total number of results generated by the query appears in the <resultCount> element within the <summary> element. Queries generating more then 20,000 <row> elements have a <resultCount> larger than the <returnCount>. If this occurs, you may want to reduce the number of identifiers in your request until the <resultCount> is less than 20,000. This ensures that you are seeing all results included in the response.

<batchMarkerRequest>

The <batchMarkerRequest> element is designed to allow programmatic requests that mirror the functionality of the MGI Batch Query tool. This request lets you upload a set of identifiers and select which gene/marker attributes to include in the response. All identifiers in the set must be of the same supported type.

This <batchMarkerRequest> element is composed of:

<requestorEmail> - The email address of the requestor. This element is defined in the http://ws.mgi.jax.org/xsd/request namespace.

<IDSet> - An optional IDType attribute and 1 or more <id> sub-elements. The <IDSet> element is defined in the http://ws.mgi.jax.org/xsd/request namespace. The optional IDType attribute must be one of the case sensitive strings defined below and is used to indicate what type of identifiers the set contains. If this attribute is omitted auto is assumed and the batchMarkerRequest will attempt to detect type of the input ids it receives. Note that this option supports an IDSet containing ids of mixed type. The <id> sub-elements each contain an individual identifier, and queries for the identifiers are case insensitive. The <id> element is defined in the http://ws.mgi.jax.org/xsd/batchType namespace.

Currently supported input identifier types:

IDType Examples

auto Any type of IDs may be used.

mgiMarker MGI:97490

symbol Pax6

nomen TP53

entrezGene 22173

ensembl ENSMUSG00000029335

vega OTTMUSG00000015006

unigene 181490

mirbase MI0005552

genbankRefseq NM_146146

uniprot P48356

go GO:0019221

refsnp rs27429143

affy1 10344624

affy2 1415680_at

<returnSet> - 1 - 5 <attribute> sub-elements. The <returnSet> element is defined in the http://ws.mgi.jax.org/xsd/request namespace. Each <attribute> element contains one of the strings defined below and is used to select specific gene attributes to be returned in the results. The <attribute> element is defined in the http://ws.mgi.jax.org/xsd/batchType namespace and corresponds to the Gene Attributes selections on the MGI Batch Query tool.

Currently supported <attribute> strings:

Attribute Elements returned for each gene/marker in the result set

nomenclature <Symbol>
<Name>
<FeatureType> - e.g. Gene, Pseudogene, QTL

location <Chr> - chromosome location
<Start> - start coordinate
<End> - end coordinate
<Strand> - sequence strand orientation (+ or -)

ensembl <ensembl> - Ensembl ID

entrezGene <entrezgene> - EntrezGene ID

vega <vega> - VEGA ID

<returnAdditionalInfo> - One of the strings defined in the table below. These are used to select an additional information data type to be returned in the results. You may select only one per request. The <returnAdditionalInfo> element is defined in the http://ws.mgi.jax.org/xsd/request namespace and corresponds to the Additional Information selection found on the MGI Batch Query tool.

Currently supported <returnAdditionalInfo> strings:

Additional Information Elements returned for each gene/marker in the result set

go <ID> - ID of the GO (Gene Ontology) term associated to the gene/marker
<Term>
<Code> - evidence code

(NOT annotations are not returned)

mp <ID> - ID of the MP (Mammalian Phenotype) term associated to the gene/marker
<Term>

(Normal annotations are not returned)

mgiAllele <ID> - MGI Allele ID
<Symbol>

genbankRefseq <genbankrefseq> - contains a GenBank (nucleotide) or RefSeq (nucleotide or protein) sequence ID associated to the gene/marker

refsnp <refsnp> - contains a RefSNP ID associated to the gene/marker

(Results include only within gene and locus region annotations)

uniprot <uniprot> - contains a UniProt (protein) sequence ID associated to the gene/marker

omim <ID> - ID of the OMIM (Human Disease) term associated to the gene/marker
<Term>

exp <anatomicalStructure> - anatomical structure examined when analyzing expression for the gene/marker
<expressed> - number of times expression was detected in the structure
<notExpressed> - number of times expression was found to be absent in the structure

Example #2 request - An example of a <batchMarkerRequest> that contains 2 MGI gene/marker IDs. It requests that nomenclature, location, EntrezGene, Ensembl, and VEGA IDs be returned as attributes, and that corresponding MP (Mammalian Phenotype) annotations be returned as additional information. Note: namespace declarations are required.
    <submitDocument xmlns:req="http://ws.mgi.jax.org/xsd/request"
                xmlns:bt="http://ws.mgi.jax.org/xsd/batchType">
        <req:batchMarkerRequest>
            <req:requestorEmail>myEmail@domain.com</req:requestorEmail>
            <req:IDSet IDType="mgiMarker">
                <bt:id>MGI:103188</bt:id>
                <bt:id>MGI:1342771</bt:id>
            </req:IDSet>
            <req:returnSet>
                <bt:attribute>nomenclature</bt:attribute>
                <bt:attribute>location</bt:attribute>
                <bt:attribute>entrezGene</bt:attribute>
                <bt:attribute>ensembl</bt:attribute>
                <bt:attribute>vega</bt:attribute>
            </req:returnSet>
            <req:returnAdditionalInfo>mgiAllele</req:returnAdditionalInfo>
        </req:batchMarkerRequest>
    </submitDocument>
    
Example #2 response - All responses to the <batchMarkerRequest> contain the following:

A <summary> element containing data about the web service version, database version, query parameters, and result counts

At least one <row> element per input identifier

Each <row> element contains an <Input> element to indicate the uploaded input identifier

An <mgiGeneMarkerID> element containing the matching gene/marker MGI ID and corresponding to the input identifier

Additional elements matching <attribute> or <returnAdditionalInfo> elements included in the request.
    <mgi:submitDocumentResponse xmlns:mgi="http://ws.mgi.jax.org/xsd">
       <mgi:summary>
          <mgi:wsVersion>1.0</mgi:wsVersion>
          <mgi:genomeBuild>36</mgi:genomeBuild>
          <mgi:databaseVersion>MGI 3.54</mgi:databaseVersion>
          <mgi:databaseDate>04/22/2008</mgi:databaseDate>
          <mgi:inputCount>2</mgi:inputCount>
          <mgi:inputType>mgiMarker</mgi:inputType>
          <mgi:returnData>
             <mgi:returnData>entrezGene</mgi:returnData>
             <mgi:returnData>nomenclature</mgi:returnData>
             <mgi:returnData>vega</mgi:returnData>
             <mgi:returnData>ensembl</mgi:returnData>
             <mgi:returnData>location</mgi:returnData>
             <mgi:returnData>mgiAllele</mgi:returnData>
          </mgi:returnData>
          <mgi:resultCount>8</mgi:resultCount>
          <mgi:returnCount>8</mgi:returnCount>
       </mgi:summary>
       <mgi:row>
          <mgi:input>MGI:103188</mgi:input>
          <mgi:inputtype>MGI</mgi:inputtype>
          <mgi:mgiGeneMarkerID>MGI:103188</mgi:mgiGeneMarkerID>
          <mgi:entrezGeneID>18028</mgi:entrezGeneID>
          <mgi:symbol>Nfib</mgi:symbol>
          <mgi:name>nuclear factor I/B</mgi:name>
          <mgi:featureType>Gene</mgi:featureType>
          <mgi:vegaID>OTTMUSG00000000395</mgi:vegaID>
          <mgi:ensemblID>ENSMUSG00000052757</mgi:ensemblID>
          <mgi:chr>4</mgi:chr>
          <mgi:strand>-</mgi:strand>
          <mgi:start>81761404</mgi:start>
          <mgi:end>82176981</mgi:end>
          <mgi:mgiAlleleID>MGI:2178748</mgi:mgiAlleleID>
       </mgi:row>
       <mgi:row>
          <mgi:input>MGI:103188</mgi:input>
          <mgi:inputtype>MGI</mgi:inputtype>
          <mgi:mgiGeneMarkerID>MGI:103188</mgi:mgiGeneMarkerID>
          <mgi:entrezGeneID>18028</mgi:entrezGeneID>
          <mgi:symbol>Nfib</mgi:symbol>
          <mgi:name>nuclear factor I/B</mgi:name>
          <mgi:featureType>Gene</mgi:featureType>
          <mgi:vegaID>OTTMUSG00000000395</mgi:vegaID>
          <mgi:ensemblID>ENSMUSG00000008575</mgi:ensemblID>
          <mgi:chr>4</mgi:chr>
          <mgi:strand>-</mgi:strand>
          <mgi:start>81761404</mgi:start>
          <mgi:end>82176981</mgi:end>
          <mgi:mgiAlleleID>MGI:3530139</mgi:mgiAlleleID>
       </mgi:row>
       <mgi:row>
          <mgi:input>MGI:1342771</mgi:input>
          <mgi:inputtype>MGI</mgi:inputtype>
          <mgi:mgiGeneMarkerID>MGI:1342771</mgi:mgiGeneMarkerID>
          <mgi:entrezGeneID>16596</mgi:entrezGeneID>
          <mgi:symbol>Klf1</mgi:symbol>
          <mgi:name>Kruppel-like factor 1 (erythroid)</mgi:name>
          <mgi:featureType>Gene</mgi:featureType>
          <mgi:vegaID/>
          <mgi:ensemblID>ENSMUSG00000054191</mgi:ensemblID>
          <mgi:chr>8</mgi:chr>
          <mgi:strand>+</mgi:strand>
          <mgi:start>87792033</mgi:start>
          <mgi:end>87795396</mgi:end>
          <mgi:mgiAlleleID>MGI:1857557</mgi:mgiAlleleID>
       </mgi:row>

       (...)

    </mgi:submitDocumentResponse>
    
Results & Limits

The relationship between a gene/marker and the selected <attribute> and/or <returnAdditionalInfo> elements is frequently not one-to-one. A <row> element is returned for all unique combinations of these associations. For example, a gene/marker associated with 3 Ensembl and 2 VEGA IDs returns 6 <row> elements.

Empty elements in the result set indicate that there is no data of that type associated to the gene/marker. For example, any input identifiers that cannot be identified by the designated IDType, or that have no gene/marker association within MGI, is returned with an empty <mgiGeneMarkerID> element. Similiarly, an empty <vega> element indicates that there is no associated VEGA ID for the gene/marker returned.

The number of <row> elements returned appears in the <returnCount> element within the <summary> element. Results are currently limited to 20,000 <row> elements.

The total number of results generated by the query appears in the <resultCount> element within the <summary> element. Queries generating more then 20,000 <row> elements have a <resultCount> larger than the <returnCount>. If this occurs, you may want to reduce the number of identifiers in your request until the <resultCount> is less than 20,000. This ensures that you are seeing all results included in the response.

Example Clients

Example clients are provided to show how to format requests and connect to the MGI Web Service.

Java Client - Java version 1.3 of the Axis2 libraries.
Perl Client - Perl version 0.60 of the SOAP::Lite module.
Python Client - Python version 0.8.4 of PyXML and version 2.42 of httplib.

Contributing Projects: Mouse Genome Database (MGD), Gene Expression Database (GXD), Mouse Tumor Biology (MTB), Gene Ontology (GO), MouseCyc
Citing These Resources Funding Information Warranty Disclaimer & Copyright Notice Send questions and comments to User Support.	last database update 04/03/2013 MGI 5.12