Resource URLs

The HGNC/wr URLs are given in the URI template notation (described by Gregorio et al, IETF draft, Nov 26, 2007). Briefly, the curly braces "{ }" define a variable embedded in the URI template. The variable must be replaced by the appropriate value to create a valid URI.

HTTP methods

The HGNC/wr resources are read-only. Therefore, the only important HTTP method is GET. The HEAD and OPTIONS methods have not yet been implemented.

URL-encoding values

The {chrspec}, {genespec} and query parameter values may contain characters that are not allowed in URLs. For instance, a space character cannot be included as-is in a URL. Such characters must be URL-encoded. In the general case, special characters are converted to ASCII-based hexadecimal percent codes, e.g. '!' to '%21'. URL-encoding is also called percent-encoding. The space (blank) character can also be encoded as '+'.

Specifying the representation

The representation of the retrieved data, i.e. the format, can be specified by appending a suffix, such as '.xml', to the URL. See Representations. Currently, the available formats are HTML and XML.

Specifying a gene

A gene can be specified in several different ways when retrieving a record in the HGNC database. The HGNC gene symbol and the HGNC identifier are the two basic specifications. The HGNC gene identifier is a number with or without the 'HGNC:' prefix.

A gene may have symbols that have been designated as 'alias', 'previous' or 'withdrawn' by HGNC. If such a symbol is used to retrieve a gene record, then the HGNC/wr system will return a redirection command to the client. This should cause the client to fetch the data using the current symbol or identifier instead. All modern browsers support redirection, while some HTTP software libraries may leave it to the programmer to write code to handle redirection.

If an 'alias', 'previous' or 'withdrawn' symbol maps to more than one current gene, then no redirection is performed. Instead, currently, the HTTP error code 404 (Not Found) is returned. This questionable behaviour may change in future versions of the HGNC/wr system.

More than one gene

It is possible to fetch more than one gene representation in a single XML document. This is currently not possible for the HTML representation. There are two different ways to do this.

The first uses the 'genes.xml/{genespecs}' URL, where {genespecs} is a semicolon-delimited string of HGNC identifiers or symbols. Alias, previous or withdrawn symbols are not allowed in this case. The order of the genes in the XML document is undefined.

The second way uses the 'genes.xml?{query}' URL, where the {query} part is a set of query parameters. These are the same parameters in format and behaviour as the ones used for the corresponding 'genes;index' URL.

This is a much more efficient way of retrieving several gene representations than issuing one request per gene. We recommend using this feature whenever possible. The only caveat is that the URL cannot be longer than some ill-defined maximum length. Keep it shorter than 4,000 characters in total.

Query parameters

Parameter key=value	Description
search=key	Search progressively for genes that match the string value. See below.
search=id	Search for the given HGNC identifier.
search=symbol	Search for the given HGNC symbol.
search=alias	Search for the given HGNC alias symbol.
search=prev_symbol	Search for the given HGNC previous symbol.
search=withdrawn	Search for the given HGNC withdrawn symbol.
search=name	Search for the given name.
search=name_alias	Search for the given name alias.
search=prev_name	Search for the given previous name.
search=gene_family	Search for genes in the given gene family.
search=locus_type	Search for the given locus type.
search=xref	Search for the cross-reference to an external database given in the form 'xdb:xkey', where xdb is the database and xkey is the entry identifier.
value={strvalue}	The string value searched for in the field specified by the 'search' parameter.
exact={boolean}	An exact string search is done, or not. The boolean is given as 'T' or 'F' (default). Ignored when 'search=key'.

Note that a valid query must contain one and only one each of both the 'search' parameter and the 'value' parameter. The parameter 'exact' is optional. See the tutorial for an example of how to build a query in a program.

The 'value={strvalue}' parameter determines the string that is searched for. It may optionally contain the wildcard characters '*' (= any characters) or '?' (= any single character).

The 'search=key' parameter is special. When used, the HGNC/wr system performs a series of different searches. As soon as a non-empty set of genes is produced by any step in this series, the search is terminated, and the result is returned to the client. The search input field available on most pages of the web site performs this operation.

The 'search=key' operation proceeds in the following order:

1. HGNC identifier (exact match, unless explicit wildcards)
2. HGNC symbol (exact match, unless explicit wildcards)
3. HGNC alias symbol (exact match, unless explicit wildcards)
4. HGNC previous symbol (exact match, unless explicit wildcards)
5. HGNC withdrawn symbol (exact match, unless explicit wildcards)
6. name (exact match, unless explicit wildcards)
7. HGNC symbol (substring match)
8. HGNC alias symbol (substring match)
9. HGNC previous symbol (substring match)
10. HGNC withdrawn symbol (substring match)
11. name (substring match)
12. cross-reference to external database (exact)