REST web-service help

Warning: Search requires JavaScript to function. more...

HGNC REST API
VGNC API extention to the REST API
Content type
Response codes
Examples

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.

HGNC REST API

There are three requests that can be made using the genenames.org REST web-service, but all use the same root URL of https://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.

"`info`" request

The info request (https://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

XML output

"`fetch`" request

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:

https://rest.genenames.org/fetch/symbol/ZNF3

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

https://rest.genenames.org/fetch/symbol/BRAF

Below are examples of a JSON and an XML response:

JSON output

XML output

"`search`" request

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:

https://rest.genenames.org/search/symbol/ZNF3

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
https://rest.genenames.org/search/BRAF	Search all searchable fields for the term BRAF
https://rest.genenames.org/search/symbol/ZNF*	Return all records that have symbols that start with ZNF
https://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
https://rest.genenames.org/search/symbol:ZNF3	An alternative form of https://rest.genenames.org/search/symbol/ZNF3
https://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
https://rest.genenames.org/search/symbol:ZNF3+OR+ZNF12	Return ZNF3 and ZNF12
https://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 https://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 https://rest.genenames.org/search/name:%22MAPK%20interacting%22+AND+locus_type:%22gene%20with%20protein%20product%22:

JSON output

XML output

Searchable field definition

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

alias_name: Other names used to refer to this gene as seen in the "Alias names" field in the gene symbol report.; https://rest.genenames.org/search/alias_name/%22A-kinase%20anchor%20protein,%20350kDa%22
alias_symbol: Other symbols used to refer to this geneas seen in the "Alias symbols" field in the gene symbol report.; https://rest.genenames.org/search/alias_symbol/BRAF1
ccds_id: Consensus CDS ID. This field may be found within the "Nucleotide resources" section of the gene symbol report.; https://rest.genenames.org/search/ccds_id/CCDS5863
curator_notes: 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.; https://rest.genenames.org/search/curator_notes/functional
ena: International Nucleotide Sequence Database Collaboration (GenBank, ENA and DDBJ) accession number(s). Found within the "Nucleotide resources" section of the gene symbol report.; https://rest.genenames.org/search/ena/M95712
ensembl_gene_id: Ensembl gene ID. Found within the "Gene resources" section of the gene symbol report.; https://rest.genenames.org/search/ensembl_gene_id/ENSG00000157764
entrez_id: Entrez gene ID. Found within the "Gene resources" section of the gene symbol report.; https://rest.genenames.org/search/entrez_id/673
hgnc_id: HGNC ID. A unique ID created by the HGNC for every approved symbol.; https://rest.genenames.org/search/hgnc_id/1097
location: The chromosomal location. For numbered chromosomes, please use two digits (e.g. 01 for chromosome 1, but 10 for chromosome 10). The X and Y chromosomes will not need to be prefixed with a 0. To search for genes on the mitochodria use the word mitochondria. Many records have the chromosome arm and the band within the chromosomal location field and so to get all records on a particular chromosome please use the wildcard * after the chromosome. Alternatively you could search all records on a particular arm of a chromosome and even the band (e.g. 01q* or 07q21.2). Please be aware that not all records have the arm and the chromosomal band as many only state the chromosome.; https://rest.genenames.org/search/location/01*
locus_group: A group name for a set of related locus types as defined by the HGNC (e.g. non-coding RNA).; https://rest.genenames.org/search/locus_group/\%22non-coding%20RNA%22
locus_type: The locus type as defined by the HGNC (e.g. RNA, transfer).; https://rest.genenames.org/search/locus_type/%22RNA,%20long%20non-coding%22
mane_select: MANE Select nucleotide accession with version (i.e. NCBI RefSeq or Ensembl transcript ID and version). Found within the "Nucleotide resources" section of the gene symbol report e.g. NM_001374258.1 or ENST00000644969.2; https://rest.genenames.org/search/locus_type/%22RNA,%20long%20non-coding%22
mgd_id: Mouse genome informatics database ID. Found within the "Homologs" section of the gene symbol report.; https://rest.genenames.org/search/mgd_id/%22MGI:88190%22
name: HGNC approved name for the gene. Equates to the "Approved name" field within the gene symbol report.; https://rest.genenames.org/search/name/%22zinc%20finger%20protein%20536%22
omim_id: An Online Mendelian Inheritance in Man (OMIM) ID; https://rest.genenames.org/search/omim_id/194510
prev_name: Gene names previously approved by the HGNC for this gene. Equates to the "Previous names" field within the gene symbol report.; https://rest.genenames.org/search/prev_name/%22solute%20carrier%20family%205%20(choline%20transporter),%20member%207%22
prev_symbol: Symbols previously approved by the HGNC for this gene. Equates to the "Previous symbols" field within the gene symbol report.; https://rest.genenames.org/search/prev_symbol/RN5S49
refseq_accession: RefSeq nucleotide accession. This field may be found within the "Nucleotide resources" section of the gene symbol report.; https://rest.genenames.org/search/refseq_accession/NM_033360
rgd_id: Rat genome database gene ID. Found within the "Homologs" section of the gene symbol report.; https://rest.genenames.org/search/rgd_id/%22RGD:2981%22
rna_central_id: An RNAcentral ID. Found within the "Nucleotide resources" section of the gene symbol report.; https://rest.genenames.org/search/rna_central_id/URS000075AC83
status: Status of the symbol report, which can be either "Approved" or "Entry Withdrawn".; https://rest.genenames.org/search/status/Approved
symbol: The HGNC approved gene symbol. Equates to the "Approved symbol" field within the gene symbol report.; https://rest.genenames.org/search/symbol/KLF4
symbol_report_tag: 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; https://rest.genenames.org/search/symbol_report_tag/Ambiguous
ucsc_id: UCSC gene ID. Found within the "Gene resources" section of the gene symbol report.; https://rest.genenames.org/search/ucsc_id/%22uc001rgp%22
uniprot_ids: UniProt protein accession. Found within the "Protein resources" section of the gene symbol report.; https://rest.genenames.org/search/uniprot_ids/P00568
vega_id: Vega gene ID. Found within the "Gene resources" section of the gene symbol report.; https://rest.genenames.org/search/vega_id/OTTHUMG00000020722

Stored field definitions

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; http://slc.bioparadigms.org/protein?GeneName=<SYMBOL>
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; http://www.hcdm.org/index.php?option=com_molecule&cdnumber=<SYMBOL>
cosmic (string): Symbol used within the Catalogue of somatic mutations in cancer for the gene; http://cancer.sanger.ac.uk/cosmic/gene/overview?ln=<SYMBOL>
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; https://www.ncbi.nlm.nih.gov/gene/<ID>
enzyme_id (string array): ENZYME EC accession number; http://enzyme.expasy.org/EC/<EC ACCESSION NUMBER>
gencc (string array): HGNC ID associated to a Gene Curation Coalition (GenCC) record.; https://search.thegencc.org/genes/<HGNC ID>
gene_group (string): HGNC gene group names to which the gene belongs.
gene_group_id (int array): HGNC gene group ID to which the gene belongs.; /data/genegroup/#!/group/<ID>
gtrnadb (string): The GtRNAdb ID to which the gene belongs. This will only appear if the gene is a tRNA.; http://gtrnadb.ucsc.edu/genomes/eukaryota/Hsapi38/genes/<gtrnadb>.html
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; http://homeodb.cbi.pku.edu.cn/gene_info.get?id=<ID>
horde_id (string): Symbol used within HORDE for the gene; http://genome.weizmann.ac.il/horde/card/index/symbol:<SYMBOL>
imgt (string): Symbol used within international ImMunoGeneTics information system; http://www.imgt.org/IMGT_GENE-DB/GENElect?query=2+<SYMBOL>&species=Homo+sapiens
intermediate_filament_db (string): ID used to link to the Human Intermediate Filament Database; http://www.interfil.org/details.php?id=<ID>
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; http://www.guidetopharmacology.org/GRAC/ObjectDisplayForward?objectId=<ID>
lncipedia (string): The LNCipedia ID to which the gene belongs. This will only appear if the gene is a long non-coding RNA.; https://lncipedia.org/db/gene/<lncipedia>
lncrnadb (string): lncRNA Database ID; http://www.lncrnadb.org/<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; http://mamit-trna.u-strasbg.fr/mutations.asp?idAA=<ID>
mane_select (string array): See mane_select within the searchable fields for the definition
merops (string): ID used to link to the MEROPS peptidase database; https://www.ebi.ac.uk/merops/cgi-bin/pepsum?id=<ID>
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; http://www.mirbase.org/cgi-bin/mirna_entry.pl?acc=<ID>
name (string): See name within the searchable fields for the definition
omim_id (int array): Online Mendelian Inheritance in Man (OMIM) ID; http://www.omim.org/entry/<ID>
orphanet (int): Orphanet ID; http://www.orpha.net/consor/cgi-bin/OC_Exp.php?Lng=GB&Expert=<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; http://tables.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>
rna_central_id (string array): See rna_central_id within the searchable fields for the definition.; https://rnacentral.org/rna/<RNACentral ID>/9606
snornabase (string): snoRNABase ID; https://www-snorna.biotoul.fr//plus.php?snoid=<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>

VGNC API extention to the REST API

It is now possible to search & fetch VGNC (vertebrate.genenames.org) data with the REST API using the same request types mentioned above in the info request, fetch request & search request sections. Just prefix the request type with vgnc/ and you will be searching and retrieving records within the VGNC sister site

The Vertebrate Gene Nomenclature Committee (VGNC) is an extension of the established HGNC (HUGO Gene Nomenclature Committee) project and is responsible for assigning standardized names to genes in vertebrate species that currently lack a nomenclature committee. For more information about the VGNC see our About the VGNC page on our sister site.

"`info`" request

Just like the info request for the HGNC data, the request is used to retrieve 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 for this type of request (i.e. https://rest.genenames.org/vgnc/info)

JSON output

XML output

"`fetch`" request

The fetch request is to retrieve particular records that contain 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. For more information about fetch please see the HGNC fetch request section above.

Below are examples of fetch results for https://rest.genenames.org/fetch/symbol/ZNF3 when using the Accept header for XML and JSON (see Content type).

JSON output

XML output

"`search`" request

The search request is more powerful than fetch for querying the database, but search will only return the fields vgnc_id, symbol and score. For more information about search see the HGNC search request section above.

Below are examples of a JSON and an XML response for the query https://rest.genenames.org/vgnc/search/symbol:RASA*+AND+status:Approved+AND+taxonomy_id:9685

JSON output

XML output

Searchable field definitions

Below is a definition list containing the fields that can be used to fetch and search data found within the VGNC symbol report record, a with example URLs for each field.

alias_name: Other names used to refer to this gene as seen in the "Alias names" field in the gene symbol report.; https://rest.genenames.org/vgnc/search/alias_name/%22cytochrome%20P450%20family%208%20subfamily%20A%20member%201%22
alias_symbol: Other symbols used to refer to this gene as seen in the "Alias symbols" field in the gene symbol report.; https://rest.genenames.org/vgnc/search/alias_symbol/cOR10A3
ensembl_gene_id: Ensembl gene ID. Found within the "Gene resources" section of the gene symbol report.; https://rest.genenames.org/vgnc/search/ensembl_gene_id/ENSBTAG00000009735
latin_species: The latin/scientific genus and species name for an organism.; https://rest.genenames.org/vgnc/search/latin_species/%22bos%20taurus%22
locus_group: A group name for a set of related locus types as defined by the HGNC (e.g. protein-coding gene).; https://rest.genenames.org/vgnc/search/locus_group/%22protein-coding%20gene%22
locus_type: The locus type as defined by the VGNC (e.g. gene with protein product).; https://rest.genenames.org/vgnc/search/locus_type/%22gene%20with%20protein%20product%22
name: VGNC approved name for the gene. Equates to the "Approved name" field within the gene symbol report.; https://rest.genenames.org/vgnc/search/name/%22alpha-1-B%20glycoprotein%22
ncbi_gene_id: NCBI Gene ID. Found within the "Gene resources" section of the gene symbol report.; https://rest.genenames.org/vgnc/search/ncbi_gene_id/518955
orthologous_hgnc_id: A human ortholog's HGNC ID that may be associated to a vertebrate ortholog.; https://rest.genenames.org/vgnc/search/orthologous_hgnc_id/HGNC:5
prev_symbol: Symbols previously approved by the VGNC for this gene. Equates to the "Previous symbols" field within the gene symbol report.; https://rest.genenames.org/vgnc/search/prev_symbol/AARS
species: The common english name for a species e.g. Cat; https://rest.genenames.org/vgnc/search/species/cat
status: Status of the symbol report, which can be either "Approved" or "Entry Withdrawn".; https://rest.genenames.org/vgnc/search/status/%22Entry%20Withdrawn%22
symbol: The VGNC approved gene symbol. Equates to the "Approved symbol" field within the gene symbol report.; https://rest.genenames.org/vgnc/search/symbol/BRAF
uniprot_id: UniProt protein accession. Found within the "Protein resources" section of the gene symbol report.; https://rest.genenames.org/vgnc/search/uniprot_id/H2QVI0
vgnc_id: VGNC ID. A unique ID created by the VGNC for every gene symbol report.; https://rest.genenames.org/vgnc/search/vgnc_id/VGNC:14003

Stored field definitions

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 </strong>search</strong> request will only contain vgnc_id, symbol and score fields per document.

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

date_approved_reserved (string)

The date the entry was first approved.

date_modified (string)

Date the entry was last modified.

date_name_changed (string)

The date the gene name was last changed.

date_symbol_changed (string)

The date the gene symbol was last changed.

date_withdrawn (string)

The date that the entry was withdrawn

ensembl_gene_id (string)

See ensembl_gene_id within the searchable fields for the definition

https://www.ensembl.org/<GENUS_SPECIES>/Gene/Summary?g=<ENSEMBL GENE ID>>

group_id (int array)

VGNC gene group ID to which the gene belongs.

https://vertebrate.genenames.org/data/genegroup/#!/group/<ID>

group_name (string array)

VGNC gene group names to which the gene belongs.

latin_species (string)

See latin_species within the searchable fields for the definition

location (string)

Chromosomal location

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

name (string)

See name within the searchable fields for the definition

ncbi_gene_id (string)

See ncbi_gene_id within the searchable fields for the definition

https://www.ncbi.nlm.nih.gov/gene/<ID>>

orthologous_gene (object array)

A list of objects which contain the following fields:

https://vertebrate.genenames.org/data/gene-symbol-report/#!/vgnc_id/<VGNC ID>

orthologous_hgnc_id (int array)

List of HGNC IDs for the human orthologous genes

https://www.genenames.org/data/gene-symbol-report/#!/hgnc_id/<HGNC ID>

prev_name (string array)

See prev_name within the searchable fields for the definition

prev_symbol (string arrray)

See prev_symbol within the searchable fields for the definition

species (string)

See species within the searchable fields for the definition

status (string)

See status within the searchable fields for the definition

symbol (string)

See symbol within the searchable fields for the definition

taxonomy_id (int)

The NCBI taxonomy ID.

https://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi?id=<TAXONOMY ID>

uniprot_id (string array)

See uniprot_id within the searchable fields for the definition

http://www.uniprot.org/uniprot/<UNIPROT ID>

uuid (string)

Unique ID held within the search server

vgnc_id (string)

See vgnc_id within the searchable fields for the definition

https://vertebrate.genenames.org/data/gene-symbol-report/#!/vgnc_id/<VGNC ID>

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" https://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.

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.

Examples

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" https://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' https://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.

#!/usr/local/bin/perl
use strict;
use warnings;

use HTTP::Tiny;
use JSON;
use Encode;
use Data::Dumper;

my $http = HTTP::Tiny->new();

my $server = 'https://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.

#!/usr/bin/python

import httplib2 as http
import json

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

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

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

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

h = http.Http()

response, content = h.request(
  target.geturl(),
  method,
  body,
  headers)

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'])
else:
  print( 'Error detected: ' + response['status'])

Ruby requests

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

#!/usr/bin/ruby

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

server='https://rest.genenames.org'
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
  exit
end

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

REST web-service help

HGNC REST API

"info" request

"fetch" request

"search" request

Searchable field definition

Stored field definitions

VGNC API extention to the REST API

"info" request

"fetch" request

"search" request

Searchable field definitions

Stored field definitions

Content type

Response codes

Examples

Query our REST API with prewritten code by the HGNC

Command line requests

Perl requests

Python requests

Ruby requests

"`info`" request

"`fetch`" request

"`search`" request

"`info`" request

"`fetch`" request

"`search`" request