We need your help in understanding the impact of the HGNC/VGNC in your research. Please take the EMBL-EBI impact survey Take survey

REST web-service help

The genenames.org REST web-service is a convenient and quick way of searching and fetching data from our database within a script/program. Users may request results as either XML or JSON making our data easier to parse.

Making a request

There are three requests that can be made using the genenames.org REST web-service, but all use the same root URL of http://rest.genenames.org/. The types of request you may use are explained below.

Please only send REST requests at a rate of 10 requests per second otherwise you may swamp the server and reduce the speed and user experience for all. If we are experiencing higher rates, causing an adverse affect on the service we may IP block the machine and send a 403 error from our servers. If you experience 403 errors please contact us via our feedback form.

Types of request


The info request (http://rest.genenames.org/info) is used to request information about the service rather than fetching any data from the server. The response from info will contain information such as when the data within the server was last updated (lastModified), the number of documents (numDoc), which fields can be queried using search and fetch (searchableFields) and which fields may be returned by fetch (storedFields). Below is an example of a JSON response and an XML response.

JSON output

"lastModified": "2013-12-05T10:09:20.58Z",
"numDoc": 38760,
"responseHeader": {
"QTime": 5,
"status": 0
"searchableFields": [
"storedFields": [

XML output

<?xml version="1.0" encoding="UTF-8"?>
 <lst name="responseHeader">
 <int name="status">0</int>
 <int name="QTime">6</int>
 <result name="response" numFound="1" start="0">
 <str name="lastModified">2013-12-05T10:09:20.58Z</str>
 <int name="numDoc">38760</int>
 <arr name="searchableFields"> 
 <arr name="storedFields">


The fetch request is the main request to retrieve particular records for the server that will return back all the fields as seen in the "storedFields" section of the info response. The fetch method requires the user to add the queriable field (as seen in the "searchableFields" section of the info) and the query term to the url. As seen below:


Fetch will not accept wildcards or multiple queries and will only accept a field/term. This does not mean that only one record will be returned however as it is allowed to ask for all records with an approved symbol (ie http://rest.genenames.org/fetch/status/Approved). Please note that this query will take a longer time to respond and will return a large amount of data (ie 38000 records). If the term contains spaces then the term will have to be quoted with double quotes like "A-kinase anchor protein, 350kDa". The quotes and spaces must be URL encoded so the " needs to be %22 and spaces need to be replaced to %20 which would create a URL like the following:


Below are examples of a JSON and an XML response:

JSON output

"name":"zinc finger protein 3",
"locus_type":"gene with protein product",
"zinc finger protein 3 (A8-51)"
"Zinc fingers, C2H2-type"
"locus_group":"protein-coding gene",

XML output

<?xml version="1.0"?>
 <lst name="responseHeader">
 <int name="status">0</int>
 <int name="QTime">0</int>
 <result name="response" numFound="1" start="0">
 <str name="hgnc_id">HGNC:13089</str>
 <str name="symbol">ZNF3</str>
 <str name="name">zinc finger protein 3</str>
 <str name="status">Approved</str>
 <str name="locus_type">gene with protein product</str>
 <arr name="prev_name">
 <str>zinc finger protein 3 (A8-51)</str>
 <arr name="alias_symbol">
 <str name="location">7q22.1</str>
 <date name="date_approved_reserved">1989-05-31T00:00:00Z</date>
 <date name="date_modified">2013-01-08T00:00:00Z</date>
 <date name="date_name_changed">2006-05-05T00:00:00Z</date>
 <arr name="ena">
 <str name="entrez_id">7551</str>
 <arr name="mgd_id">
 <int name="kznf_gene_catalog">460</int>
 <str name="cosmic">ZNF3</str>
 <arr name="refseq_accession">
 <arr name="gene_family">
 <str>Zinc fingers, C2H2-type</str>
 <str name="ensembl_gene_id">ENSG00000166526</str>
 <arr name="ccds_id">
 <str name="locus_group">protein-coding gene</str>
 <int name="omim_id">194510</int>
 <arr name="uniprot_ids">
 <str name="ucsc_id">uc003usr</str>
 <arr name="rgd_id">
 <str name="uuid">e14b1f27-688c-48a3-ad48-bcb8b046ca27</str>
 <long name="_version_">1453576069925830657</long></doc>


The search request is more powerful than fetch for querying the database, but search will only returns the fields hgnc_id, symbol and score. This is because this tool is mainly intended to query the server to find possible entries of interest or to check data (such as your own symbols) rather than to fetch information about the genes. If you want to retrieve all the data for a set of genes from the search result, the user could use the hgnc_id returned by search to then fire off a fetch request by hgnc_id. Searchrequest URLs can be very similar to the fetch request URL by substituting /fetch/ with /search/ like so:


The above is a simple query to search the server for records that have a symbol named ZNF3. Search can do more powerful request then just a simple look up on a field as seen in the examples below:

Search example Note
http://rest.genenames.org/search/BRAF Search all searchable fields for the term BRAF
http://rest.genenames.org/search/symbol/ZNF* Return all records that have symbols that start with ZNF
http://rest.genenames.org/search/symbol/ZNF? Return all records that have symbols that start with ZNF with and includes an extra character after ZNF ie ZNF3 but not ZNF12
http://rest.genenames.org/search/symbol:ZNF3 An alternative form of http://rest.genenames.org/search/symbol/ZNF3
http://rest.genenames.org/search/symbol:ZNF*+AND+status:Approved Return all records that have symbols that start with ZNF which have been approved by the HGNC
http://rest.genenames.org/search/symbol:ZNF3+OR+ZNF12 Return ZNF3 and ZNF12
http://rest.genenames.org/search/symbol:ZNF*+NOT+status:Approved Return all records that have symbols that start with ZNF which are not approved (ie entry withdrawn)

If a phrase (ie multiple words) is used as within a search term, the term will have to be double quoted and URL encoded. For example the term "Entry withdrawn" would become %22Entry%20withdrawn%22 and so an alternative to the last example within the table above would be http://rest.genenames.org/search/symbol:ZNF*+AND+status:%22Entry%20withdrawn%22

See the Advanced search topic in the search help page for more information about searching.

Below are examples of a JSON and an XML response for the query http://rest.genenames.org/search/name:%22MAP%20kinase%20interacting%22+AND+locus_type:%22gene%20with%20protein%20product%22:

JSON output


XML output

<?xml version="1.0"?>
<lst name="responseHeader">
 <int name="status">0</int>
 <int name="QTime">1</int>
<result name="response" numFound="2" start="0" maxScore="5.930616">
 <str name="hgnc_id">HGNC:7110</str>
 <str name="symbol">MKNK1</str>
 <float name="score">5.930616</float></doc>
 <str name="hgnc_id">HGNC:7111</str>
 <str name="symbol">MKNK2</str>
 <float name="score">5.930616</float></doc>

Content type

As you may have worked out from the earlier sections there are two result formats you can request from the server (more may follow in future) which are JSON and XML. As with most REST APIs you select your result format by sending a header containing an Accept within your request. If you are using a web browser such as safari or firefox the browser will send an Accept:text/xml within the header (the REST servers default type) so browsers will always return XML. Using a command line tool or your own program/script you can select the output format by setting the Accept as part of your request header. Below is an example of setting the Accept content-type and requesting info using curl:

curl -H"Accept:application/json" http://rest.genenames.org/info

Below is a table of content types that the server can return:

Format Content-type Note
XML text/xml The XML returned using this content-type is indented and on multiple lines so that the XML can be read by users easily. XML can be easily parsed by many programming lanuages using pre-existing modules/packages. If your client sends an Accept:*/* with a request header then it will be this content-type that will be used.
JSON application/json JavaScript compatible generic text based serialisation format. Supported by many programming languages. This type will not be easy to read by users as the text is condensed to one line with unnecessary spaces removed, but is our recommended type for parsing within a program/script.

Searchable fields

Below is a definition list containing the fields that can be used to fetch and search records found on our server with example URLs for each field.

Other names used to refer to this gene as seen in the "Alias names" field in the gene symbol report.
Other symbols used to refer to this geneas seen in the "Alias symbols" field in the gene symbol report.
Consensus CDS ID. This field may be found within the "Nucleotide resources" section of the gene symbol report.
This field contains additional information related to the entry that has been manually added by an HGNC curator as seen in the "Curator notes" field in the gene symbol report.
International Nucleotide Sequence Database Collaboration (GenBank, ENA and DDBJ) accession number(s). Found within the "Nucleotide resources" section of the gene symbol report.
Ensembl gene ID. Found within the "Gene resources" section of the gene symbol report.
Entrez gene ID. Found within the "Gene resources" section of the gene symbol report.
HGNC ID. A unique ID created by the HGNC for every approved symbol.
A group name for a set of related locus types as defined by the HGNC (e.g. non-coding RNA).
The locus type as defined by the HGNC (e.g. RNA, transfer).
Mouse genome informatics database ID. Found within the "Homologs" section of the gene symbol report.
HGNC approved name for the gene. Equates to the "Approved name" field within the gene symbol report.
Gene names previously approved by the HGNC for this gene. Equates to the "Previous names" field within the gene symbol report.
Symbols previously approved by the HGNC for this gene. Equates to the "Previous symbols" field within the gene symbol report.
RefSeq nucleotide accession. This field may be found within the "Nucleotide resources" section of the gene symbol report.
Rat genome database gene ID. Found within the "Homologs" section of the gene symbol report.
Status of the symbol report, which can be either "Approved" or "Entry Withdrawn".
The HGNC approved gene symbol. Equates to the "Approved symbol" field within the gene symbol report.
The tag that may appear next to the title of the symbol report. The tag can be "Ambigous" for ambiguous locus type genes, "Placeholder symbol" and "Stable symbol". The tag is case sensitive so please use an uppercase letter at the beginning as seen in the previous sentence
UCSC gene ID. Found within the "Gene resources" section of the gene symbol report.
UniProt protein accession. Found within the "Protein resources" section of the gene symbol report.
Vega gene ID. Found within the "Gene resources" section of the gene symbol report.

Stored fields

The definition list below shows all the fields that could possibly be returned within a fetch request and an example of a linking URL that would use the data within the field. Results of a search request will only contain hgnc_id, symbol and score fields per document.

agr (string)
The Alliance of Genomic Resources HGNC ID for the Human gene page within the resource. Use this ID to link to the resource as seen in the example below
https://www.alliancegenome.org/gene/<AGR HGNC ID>
alias_name (string array)
See alias_name within the searchable fields for the definition
alias_symbol (string array)
See alias_symbol within the searchable fields for the definition
bioparadigms_slc (string)
Symbol used to link to the SLC tables database at bioparadigms.org for the gene
ccds_id  (string array)
See ccds_id within the searchable fields for the definition
https://www.ncbi.nlm.nih.gov/CCDS/CcdsBrowse.cgi?REQUEST=CCDS&DATA=<CCDS ID>
cd (string)
Symbol used within the Human Cell Differentiation Molecule database for the gene
cosmic (string)
Symbol used within the Catalogue of somatic mutations in cancer for the gene
curator_notes (string array)
See curator_notes within the searchable fields for the definition
date_approved_reserved (date)
The date the entry was first approved.
date_modified (date)
Date the entry was last modified.
date_name_changed (date)
The date the gene name was last changed.
date_symbol_changed (date)
The date the gene symbol was last changed.
ena (string array)
See ena within the searchable fields for the definition
https://www.ebi.ac.uk/ena/data/view/<ENA ACCESSION>
ensembl_gene_id (string)
See ensembl_gene_id within the searchable fields for the definition
https://www.ensembl.org/Homo_sapiens/Gene/Summary?g=<ENSEMBL GENE ID>
entrez_id (string)
See entrez_id within the searchable fields for the definition
enzyme_id (string array)
ENZYME EC accession number
http://enzyme.expasy.org/EC/<EC ACCESSION NUMBER>
gene_family (string array)
HGNC gene group names to which the gene belongs.
gene_family_id (int array)
HGNC gene group ID to which the gene belongs.
gtrnadb (string)
The GtRNAdb ID to which the gene belongs. This will only appear if the gene is a tRNA.
hgnc_id (string)
See hgnc_id within the searchable fields for the definition
/data/gene-symbol-report/#!/hgnc_id/<HGNC ID>
homeodb (int)
Homeobox Database ID
horde_id (string)
Symbol used within HORDE for the gene
imgt (string)
Symbol used within international ImMunoGeneTics information system
intermediate_filament_db (string)
ID used to link to the Human Intermediate Filament Database
iuphar (string)
The objectId used to link to the IUPHAR/BPS Guide to PHARMACOLOGY database. To link to IUPHAR/BPS Guide to PHARMACOLOGY database only use the number (only use 1 from the result objectId:1) in the example URL
kznf_gene_catalog (int)
ID used to link to the Human KZNF Gene Catalog
lncipedia (string)
The LNCipedia ID to which the gene belongs. This will only appear if the gene is a long non-coding RNA.
lncrnadb (string)
lncRNA Database ID
location (string)
Cytogenetic location of the gene (e.g. 2q34).
locus_group (string)
See locus_group within the searchable fields for the definition
locus_type (string)
See locus_type within the searchable fields for the definition
lsdb (string array)
The name of the Locus Specific Mutation Database and URL for the gene separated by a | character
eg Mutations of the ATP-binding Cassette Transporter Retina|http://www.retina-international.org/files/sci-news/abcrmut.htm
mamit-trnadb (int)
ID to link to the Mamit-tRNA database
merops (string)
ID used to link to the MEROPS peptidase database
mgd_id (string array)
See mgd_id within the searchable fields for the definition
http://www.informatics.jax.org/marker/<MGD ID>
mirbase (string)
miRBase ID
name (string)
See name within the searchable fields for the definition
omim_id (int array)
Online Mendelian Inheritance in Man (OMIM) ID
orphanet (int)
Orphanet ID
prev_name (string array)
See prev_name within the searchable fields for the definition
prev_symbol (string array)
See prev_symbol within the searchable fields for the definition
pseudogene.org (string)
Pseudogene.org ID
pubmed_id (long array)
Pubmed and Europe Pubmed Central PMIDs
https://www.ncbi.nlm.nih.gov/pubmed/<PMID> and https://europepmc.org/search/?page=1&query=<PMID>
refseq_accession (string array)
See refseq_accession within the searchable fields for the definition
https://www.ncbi.nlm.nih.gov/nuccore/<REFSEQ ACCESSION>
rgd_id (string array)
See rgd_id within the searchable fields for the definition. To use the ID to link to RGD remove "RGD:" from the ID
http://rgd.mcw.edu/rgdweb/report/gene/main.html?id=<RGD ID>
snornabase (string)
snoRNABase ID
status (string)
See status within the searchable fields for the definition
symbol (string)
See symbol within the searchable fields for the definition
symbol_report_tag (string)
See symbol_report_tag within the searchable fields for the definition
ucsc_id (string)
See ucsc_id within the searchable fields for the definition
uniprot_ids (string array)
See uniprot_ids within the searchable fields for the definition
http://www.uniprot.org/uniprot/<UNIPROT ID>
uuid (string)
Unique ID held within the search server
vega_id (string)
See vega_id within the searchable fields for the definition
http://vega.sanger.ac.uk/Homo_sapiens/Gene/Sequence?db=core;g=<VEGA GENE ID>

Response codes

Our REST service responds to requests using standard  HTTP status codes  which should be used to programatically detect when a request has succeeded or failed. Look for a response code of 200  as the mark of a successful request. Below are all the possible response code the REST service may return.

Response code Name Notes
200 OK Successful request.
400 Bad Request Occurs if the user has passed an incorrect URL format or used a field that does not exist.
404 Not Found Type of request does not exist. Must be an info, fetch or search.
415 Unsupported Media Type Incorrect content-type in Accept within the request header.
500 Internal Server Error Error within the program that runs the service. If you see this response code please send us an email explaining when you ran the query and the nature of the request.
503 Service Unavailable REST service temporarily unavailable. 


The REST service can be used by many clients and many programming languages. Below you will find several examples of using the REST service which we hope will help you develop your own program/script. It is important to check the response code to see if the request was successful (ie response code 200).

Query our REST API with prewritten code by the HGNC

We have created a perl script which will return tab separated tabular data containing HGNC gene information for each gene ID specified in the user provided file. The script is call get-gene-info and is available from our github repo. The script utilises the HGNC REST service and allows the user to retrieve any data that is displayed within our gene symbol reports

This code will help many people that are wanting to use our REST API however if you think that this tool does not suit your needs, the code itself is a good starting point for developing your own as it queries the REST API in batches so that the REST service is not bombarded with requests.

A video on how to download and install the get-gene-info can be seen below

Command line requests

Command line examples of downloading data from the REST service using curl and wget.

# Retrieve REST service information as JSON using curl
# -H = Add custom header 
curl -H"Accept:application/json" http://rest.genenames.org/info

# Fetch gene symbol record for HGNC ID 1097 as XML using wget
# -q = quiet
# -O- = Write to stdout
# --header = Add custom header
wget -qO- --header='Accept:text/xml' http://rest.genenames.org/fetch/hgnc_id/1097

Perl requests

Using perl to ask how many genes contain the phrase "MAP kinase interacting" within the approved name and also have a locus type of "gene with protein product". The Perl code below utilises the modules JSON and HTTP::Tiny which you may need to download and install from CPAN.

use strict;
use warnings;

use HTTP::Tiny;
use JSON;
use Encode; use Data::Dumper; my \$http = HTTP::Tiny->new(); my $server = 'http://rest.genenames.org'; my $request_type= '/search'; my $query = '/name:%22MAP%20kinase%20interacting%22' . '+AND+' . 'locus_type:%22gene%20with%20protein%20product%22'; my $response = $http->get($server.$request_type.$query, { headers => { 'Accept' => 'application/json' } }); die "Failed!\n" if $response->{status} ne '200'; my $json_bytes = encode('UTF-8', $response->{content}); my $result = decode_json($json_bytes); my $statement = q{There are %d genes that contain the phrase } . q{"MAP kinase interacting" } . q{within the approved name which have the locus type} . q{"gene with protein product"}; printf $statement, $result->{response}->{numFound};

Python requests

This example uses python to display the approved gene symbol for a given HGNC ID using fetch to return a JSON object. In order to run the example below you may need to install the httplib2 library.


import httplib2 as http
import json

from urlparse import urlparse
except ImportError:
from urllib.parse import urlparse

headers = {
'Accept': 'application/json',

uri = 'http://rest.genenames.org'
path = '/fetch/hgnc_id/1097'

target = urlparse(uri+path)
method = 'GET'
body = ''

h = http.Http()

response, content = h.request(

if response['status'] == '200':
# assume that content is a json reply
# parse content with the json module 
data = json.loads(content)
print 'Symbol:' + data['response']['docs'][0]['symbol']

print 'Error detected: ' + response['status']

Ruby requests

Fetch gene symbol report information as JSON for the gene which has BRAF as the approved symbol.


require 'net/http'
require 'uri'
require 'rubygems'
require 'json'
require 'pp'

get_path = '/fetch/symbol/braf'

url = URI.parse(server)
http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(get_path, {'Accept' => 'application/json'})
response = http.request(request)

if response.code != "200"
puts "Invalid response: #{response.code}"
puts response.body

result = JSON.parse(response.body)
pp result