About   Help   FAQ
MGI Web Service

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:

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

  2. <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:

    IDTypeExamples
    autoAny type of IDs may be used.
    symbolPax6
    nomenTP53
    entrezGene22173
    ensemblENSMUSG00000029335
    vegaOTTMUSG00000015006
    unigene181490
    mirbaseMI0005552
    genbankRefseqNM_146146
    uniprotP48356
    goGO:0019221
    refsnprs27429143
    affy110344624
    affy21415680_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:
  1. A <summary> element containing data about the web service version, database version, query parameters, and result counts
  2. At least one <row> element per input identifier
  3. An <Input> element to indicate the uploaded input identifier
  4. 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:
  1. <requestorEmail> - The email address of the requestor. This element is defined in the http://ws.mgi.jax.org/xsd/request namespace.

  2. <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:

    IDTypeExamples
    autoAny type of IDs may be used.
    mgiMarkerMGI:97490
    symbolPax6
    nomenTP53
    entrezGene22173
    ensemblENSMUSG00000029335
    vegaOTTMUSG00000015006
    unigene181490
    mirbaseMI0005552
    genbankRefseqNM_146146
    uniprotP48356
    goGO:0019221
    refsnprs27429143
    affy110344624
    affy21415680_at


  3. <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:

    AttributeElements 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


  4. <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 InformationElements 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:
  1. A <summary> element containing data about the web service version, database version, query parameters, and result counts
  2. At least one <row> element per input identifier
  3. Each <row> element contains an <Input> element to indicate the uploaded input identifier
  4. An <mgiGeneMarkerID> element containing the matching gene/marker MGI ID and corresponding to the input identifier
  5. 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
11/18/2014
MGI 5.20
The Jackson Laboratory