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 handle which supports 'POST' and 'DELETE').

The API key is a key (SHA1 hash) 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: 039583F9182AE1F7C343746B9B54C1F1BF1678A9

Added as a cookie as follows:

Cookie: ApiKey=039583F9182AE1F7C343746B9B54C1F1BF1678A9

Added as a parameter to the url request as follows:

http://api.omim.org/....?...&apiKey=039583F9182AE1F7C343746B9B54C1F1BF1678A9

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:

http://api.omim.org/api/html/entry.html

And the page to add the API to your browser cookies is:

http://api.omim.org/api/html/apiKey.html

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

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

Gene map entries are limited to 100 per request.

The rate of requests is currently limited to 4 requests per second.

Your client will be throttled if you exceed the maximum rate, a 409 http status will be returned. Note that repeated requests which get a 409 will lengthen the interval before your access is restored, and if more than thirty 409's are generated your client will be banned for six hours after which access will be restored.

Two API hosts are available, one is located in the United States:

api.omim.org

And one is located in Europe:

api.europe.omim.org

You should use the API host located closest to you.

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:

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

Multiple MIM numbers can be specified as follows:

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

or as follows:

http://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:

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

or:

http://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

http://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:

http://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:

http://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

Solr Query Syntax - Solr Wiki

Apache Lucene - Query Parser Syntax

Solr Extended Dismax Query Parser

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

For example:

http://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:

http://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:

http://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:

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

is the same as:

http://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:

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

'referenceList'

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

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

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:

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

Multiple MIM numbers can be specified as follows:

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

or as follows:

http://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:

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

or:

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

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

For example:

http://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:

http://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

Clinical Synopsis Search Fields

Solr Query Syntax - Solr Wiki

Apache Lucene - Query Parser Syntax

Solr Extended Dismax Query Parser

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

For example:

http://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:

http://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:

http://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:

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

is the same as:

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

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:

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

Multiple MIM numbers can be specified as follows:

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

Or as follows:

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

To retrieve the gene map entry for sequence ID 10:

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

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

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

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

http://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:

http://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:

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

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

http://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:

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

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

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

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

http://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

Gene Map Search Fields

Solr Query Syntax - Solr Wiki

Apache Lucene - Query Parser Syntax

Solr Extended Dismax Query Parser

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

For example:

http://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:

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

is the same as:

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

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

The 'html' handler is used to return specific files from the API, and is only useful to the API HTML Interface

For example:

http://api.omim.org/api/html/entry.html

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):

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

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

http://api.omim.org/api/apiKey

This is here only to support the API html interface.

The 'dump' handle is used to return dump/debug data from the API.

For example:

http://api.omim.org/api/dump