OMIM API

The OMIM API URLs are organized in a very simple fashion:

/api/[handler]?[parameters]

/api/[handler]/[component]?[parameters]

/api/[handler]/[action]?[parameters]

The handler refers to the data object, such as an entry or a clinical synopsis.

The component is optional and refers to a specific data component within a data object for example references within an entry.

The action is optional and refers to an action to be performed on a data object, such as a search for entries.

For basic 'GET's, the component or action are usually optional.

The parameters would include things such as MIM numbers, data retrieval options and data formatting options.

Since this is a read-only database, 'GET' is the only HTTP method for public access, all other HTTP methods will return an error (except for the apiKey handler which supports 'POST' and 'DELETE' to add/remove the apiKey from the cookies).

Basics:

Handlers:

The API key is a key that is unique to every developer wanting to access the API. It is allocated by OMIM and should not be shared. This has to be included with every request and is validated before the request is processed. There are three ways in which it can be included with a request.

Added as an HTTP Header as follows:

ApiKey: nfNEOscLNWWXdSmUoMLPPA

Added as a cookie as follows:

Cookie: ApiKey=nfNEOscLNWWXdSmUoMLPPA

Added as a parameter to the url request as follows:

https://api.omim.org/....?...&apiKey=nfNEOscLNWWXdSmUoMLPPA

Note that the API key parameter name is case-sensitive.

There are a number of generic parameters which are supported by all handler, these being:

The API provides a simple, yet powerful, HTML based interface to see how urls are structured.

The home page of the HTML based interface is:

https://api.omim.org/api/html

The API will limit how many entries can be retrieved in a single request.

Entries and clinical synopses are limited to 20 per request if any 'includes' are specified, otherwise there is no limit.

Gene map entries are limited to 100 per request.

Results can be retrieved in batches using the 'start' and 'limit' parameters as follows:

...start=0&limit=20...
...start=20&limit=20..
...start=40&limit=20..


The API supports gzip compression so, if possible, you should enable gzip compression in your client to reduce network traffic. Compression can reduce the size of responses by a factor of 4 or 5 which is advantageous in bandwidth-constrained environments.

Compression is automatically supported in some clients, whereas it needs to be specifically enabled in others. Please check the documentation for the client you are using.

The HTTP header indicating that your client can receive a compressed response is as follows:

Accept-Encoding: gzip

For example curl does not enable gzip compression by default, so this will receive an uncompressed response:

curl "https://api.omim.org/api/..."

Adding the HTTP header to will receive a compressed response:

curl -H "Accept-Encoding: gzip" "https://api.omim.org/api/..." | gunzip

The API host is:

api.omim.org

The API returns the following HTTP status codes:

The entry handler supports the following actions/components:

[none]

This is the default case and requires one parameter 'mimNumber' specifying the MIM entry to be retrieved, for example:

https://api.omim.org/api/entry?mimNumber=100100

Multiple MIM numbers can be specified as follows:

https://api.omim.org/api/entry?mimNumber=100100&mimNumber=100200

or as follows:

https://api.omim.org/api/entry?mimNumber=100100,100200

This will return the MIM number, the prefix, the status and the titles.

Additional content can be retrieved using the 'include' parameter, the includes are as follows:

For example:

https://api.omim.org/api/entry?mimNumber=100100&include=text&include=geneMap

or:

https://api.omim.org/api/entry?mimNumber=100100&include=text,geneMap

By default the 'text' include will return the entire text which can be quite long. You can specify which text section(s) is returned by appending a colon followed by the text section name to 'text', for example:

https://api.omim.org/api/entry?mimNumber=100100&include=text:clinicalFeatures

The text sections are:

Finally if all the data was needed, one could just specify:

For example:

https://api.omim.org/api/entry?mimNumber=100100&include=all

It is strongly recommended that only the data that is needed is retrieved in a request. Retrieving unneeded data means that your request will take longer than it normally would.

There is also an 'exclude' parameter to exclude unwanted sections, for example you might want all the data except for the clinical synopsis:

https://api.omim.org/api/entry?mimNumber=100100&include=all&exclude=clinicalSynopsis

'search'

Searching is provided by SOLR and uses the extended dismax parser:

OMIM Search Help

OMIM Search Fields

Apache SOLR

Apache Lucene

SOLR Help

SOLR Searching Help

This allows the client to perform a search with the following parameters:

For example:

https://api.omim.org/api/entry/search?search=duchenne&start=0&limit=20

Additionally all the parameters listed in the section above also apply, for example:

https://api.omim.org/api/entry/search?search=duchenne&start=0&limit=20&include=geneMap

The 'operator' parameter is optional and can be used to require returned documents to contain all the terms in the search:

The 'sort' parameter takes the any of the search fields available in the entry index, some useful sort orders include:

For example:

https://api.omim.org/api/entry/search?search=duchenne&sort=score+desc

If unspecified, the sort defaults to 'score desc'. Note that the sort order ('asc' or 'desc') is required.

The 'retrieve' parameter allows the retrieval of the gene map or clinical synopses corresponding to the entries instead of the entries themselves:

Note that search can also be done through the search handler, in this case the handler and the action are flipped, so:

https://api.omim.org/api/entry/search?search=duchenne&start=0&limit=20&include=geneMap

is the same as:

https://api.omim.org/api/search/entry?search=duchenne&start=0&limit=20&include=geneMap

'allelicVariantList'

This allows the client to retrieve the allelic variants for the specified MIM entry, for example:

https://api.omim.org/api/entry/allelicVariantList?mimNumber=100100

'referenceList'

This allows the client to retrieve the references for the specified MIM entry, for example:

https://api.omim.org/api/entry/referenceList?mimNumber=100100

Entry Data:

Entry Allelic Variant Data:

Entry Reference Data:

The clinical synopsis handler supports the following actions/components:

[none]

This is the default case and requires one parameter 'mimNumber' specifying the MIM entry to be retrieved, for example:

https://api.omim.org/api/clinicalSynopsis?mimNumber=100100

Multiple MIM numbers can be specified as follows:

https://api.omim.org/api/clinicalSynopsis?mimNumber=100100&mimNumber=100200

or as follows:

https://api.omim.org/api/clinicalSynopsis?mimNumber=100100,100200

This will return the MIM number, the prefix, the status and the titles.

Additional content can be retrieved using the 'include' parameter, the includes are as follows:

For example:

https://api.omim.org/api/clinicalSynopsis?mimNumber=100100&include=clinicalSynopsis&include=externalLinks

or:

https://api.omim.org/api/clinicalSynopsis?mimNumber=100100&include=clinicalSynopsis,externalLinks

Finally if all the data was needed, one could just specify:

For example:

https://api.omim.org/api/clinicalSynopsis?mimNumber=100100&include=all

It is strongly recommended that only the data that is needed is retrieved in a request. Retrieving unneeded data means that your request will take longer than it should.

There is also an 'exclude' parameter to exclude unwanted sections, for example you might want all the data except for the external links:

https://api.omim.org/api/clinicalSynopsis?mimNumber=100100&include=all&exclude=externalLinks

'search'

Searching is provided by SOLR and uses the extended dismax parser:

OMIM Search Help

OMIM Search Fields

Apache SOLR

Apache Lucene

SOLR Help

SOLR Searching Help

This allows the client to perform a search with the following parameters:

For example:

https://api.omim.org/api/clinicalSynopsis/search?search=disorder&start=0&limit=20

Additionally all the parameters listed in the section above also apply, for example:

https://api.omim.org/api/clinicalSynopsis/search?search=disorder&start=0&limit=20&include=all

The 'sort' parameter takes the any of the search fields available in the clinical synopsis index, some useful sort orders include:

For example:

https://api.omim.org/api/clinicalSynopsis/search?search=disorder&sort=score+desc

If unspecified, the sort defaults to 'score desc'. Note that the sort order ('asc' or 'desc') is required.

Note that search can also be done through the search handler, in this case the handler>and the action are flipped, so:

https://api.omim.org/api/clinicalSynopsis/search?search=disorder&start=0&limit=20

is the same as:

https://api.omim.org/api/search/clinicalSynopsis?search=disorder&start=0&limit=20

Clinical Synopsis Data:

The gene map handler supports the following actions/components:

[none]

This is the default case and supports three different parameters to retrieve data ('chromosomeSort' is a sub-parameter of 'chromosome'):

The 'sequenceID' and 'chromosome/chromosomeSort' parameters also support the 'start' and 'limit' parameters to support navigation across the map:

Additionally the 'phenotypeExists' flag can be used to restrict the entries returned to those with or without phenotypes, the default is to return all entries:

For example, to retrieve the gene map entry for 100100:

https://api.omim.org/api/geneMap?mimNumber=100100

Multiple MIM numbers can be specified as follows:

https://api.omim.org/api/geneMap?mimNumber=100100&mimNumber=100200

Or as follows:

https://api.omim.org/api/geneMap?mimNumber=100100,100200

To retrieve the gene map entry for sequence ID 10:

https://api.omim.org/api/geneMap?sequenceID=10

To retrieve the next 10 entries in the gene map starting from sequence ID 10:

https://api.omim.org/api/geneMap?sequenceID=10&limit=10

To get the subsequent 10 entries, the url would be:

https://api.omim.org/api/geneMap?sequenceID=20&limit=10

In the two cases above the 'start' parameter defaults to 0, but you can set to a negative value:

https://api.omim.org/api/geneMap?sequenceID=20&start=-4&limit=10

To retrieve the first 10 entries in the gene map for chromosome 1, the url would be:

https://api.omim.org/api/geneMap?chromosome=1&start=0&limit=10

And to retrieve the next 10 entries, the url would be:

https://api.omim.org/api/geneMap?chromosome=1&start=10&limit=10

The 'chromosomeSort' parameter can also be used to retrieve entries on a chromosome.

To retrieve the first 10 entries in the gene map for chromosome 1, the url would be:

https://api.omim.org/api/geneMap?chromosome=1&chromosomeSort=1limit=10

And to retrieve the next 10 entries, the url would be:

https://api.omim.org/api/geneMap?chromosome=1&chromosomeSort=10&limit=10

This can be mixed with 'start' parameter as well:

https://api.omim.org/api/geneMap?chromosome=1&chromosomeSort=1&start=1&limit=10

The 'sequenceID' and 'chromosomeSort' parameters should not be considered stable beyond the scope of a day (the gene map is updated on a daily basis).

'search'

Searching is provided by SOLR and uses the extended dismax parser:

OMIM Search Help

OMIM Search Fields

Apache SOLR

Apache Lucene

SOLR Help

SOLR Searching Help

This allows the client to perform a search with the following parameters:

For example:

https://api.omim.org/api/geneMap/search?search=kinase&start=0&limit=20

The 'sort' parameter takes the any of the search fields available in the gene map index, some useful sort orders include:

If unspecified, the sort defaults to 'score desc'. Note that the sort order ('asc' or 'desc') is required.

Note that search can also be done through the search handler, in this case the handler and the action are flipped, so:

https://api.omim.org/api/geneMap/search?search=kinase&start=0&limit=20

is the same as:

https://api.omim.org/api/search/geneMap?search=kinase&start=0&limit=20

Gene Map Data:

The 'search' handler is used for searching and is covered in the four handlers above.

Search Response Data:

The 'status' handler can be used to check the API status.

For example:

https://api.omim.org/api/status

The apiKey handler allows the API html interface to set an API key in the browser cookies. It supports only one parameter:

For example to set a key in the browser cookies ('POST' method only):

https://api.omim.org/api/apiKey?apiKey=foo

And to remove a key from the browser cookies ('DELETE' method only):

https://api.omim.org/api/apiKey

This is here only to support the API html interface.