Skip to Navigation

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.

Contents  

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.

Types of request

info
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": [
 "vega_id",
 "locus_group",
 "alias_symbol",
 "prev_name",
 "refseq_accession",
 "hgnc_id",
 "entrez_id",
 "symbol",
 "name",
 "mgd_id",
 "prev_symbol",
 "alias_name",
 "status",
 "locus_type",
 "rgd_id",
 "ensembl_gene_id",
 "ucsc_id",
 "uniprot_ids",
 "ena",
 "ccds_id"
 ],
 "storedFields": [
 "gene_family",
 "vega_id",
 "locus_group",
 "alias_symbol",
 "_version_",
 "uuid",
 "prev_name",
 "refseq_accession",
 "mirbase",
 "lsdb",
 "gene_family_id",
 "homeodb",
 "hgnc_id",
 "cosmic",
 "entrez_id",
 "symbol",
 "location",
 "name",
 "mgd_id",
 "snornabase",
 "prev_symbol",
 "bioparadigms_slc",
 "orphanet",
 "alias_name",
 "date_approved_reserved",
 "status",
 "pseudogene.org",
 "horde_id",
 "merops",
 "locus_type",
 "imgt",
 "iuphar",
 "rgd_id",
 "kznf_gene_catalog",
 "ensembl_gene_id",
 "mamit-trnadb",
 "omim_id",
 "date_name_changed",
 "cd",
 "date_modified",
 "ucsc_id",
 "lncrnadb",
 "enzyme_id",
 "uniprot_ids",
 "intermediate_filament_db",
 "ena",
 "ccds_id",
 "pubmed_id",
 "date_symbol_changed"
 ]
}
XML output

<?xml version="1.0" encoding="UTF-8"?>
<response>
 <lst name="responseHeader">
 <int name="status">0</int>
 <int name="QTime">6</int>
 </lst>
 <result name="response" numFound="1" start="0">
 <doc>
 <str name="lastModified">2013-12-05T10:09:20.58Z</str>
 <int name="numDoc">38760</int>
 <arr name="searchableFields"> 
 <str>vega_id</str> 
 <str>locus_group</str> 
 <str>alias_symbol</str> 
 <str>prev_name</str> 
 <str>refseq_accession</str> 
 <str>hgnc_id</str> 
 <str>entrez_id</str> 
 <str>symbol</str> 
 <str>name</str> 
 <str>mgd_id</str> 
 <str>prev_symbol</str> 
 <str>alias_name</str> 
 <str>status</str> 
 <str>locus_type</str> 
 <str>rgd_id</str> 
 <str>ensembl_gene_id</str> 
 <str>ucsc_id</str> 
 <str>uniprot_ids</str> 
 <str>ena</str> 
 <str>ccds_id</str>
 </arr>
 <arr name="storedFields">
 <str>gene_family</str>
 <str>vega_id</str>
 <str>locus_group</str>
 <str>alias_symbol</str>
 <str>_version_</str>
 <str>uuid</str>
 <str>prev_name</str>
 <str>refseq_accession</str>
 <str>mirbase</str>
 <str>lsdb</str>
 <str>gene_family_id</str>
 <str>homeodb</str>
 <str>hgnc_id</str>
 <str>cosmic</str>
 <str>entrez_id</str>
 <str>symbol</str>
 <str>location</str>
 <str>name</str>
 <str>mgd_id</str>
 <str>snornabase</str>
 <str>prev_symbol</str>
 <str>bioparadigms_slc</str>
 <str>orphanet</str>
 <str>alias_name</str>
 <str>date_approved_reserved</str>
 <str>status</str>
 <str>pseudogene.org</str>
 <str>horde_id</str>
 <str>merops</str>
 <str>locus_type</str>
 <str>imgt</str>
 <str>iuphar</str>
 <str>rgd_id</str>
 <str>kznf_gene_catalog</str>
 <str>ensembl_gene_id</str>
 <str>mamit-trnadb</str>
 <str>omim_id</str>
 <str>date_name_changed</str>
 <str>cd</str>
 <str>date_modified</str>
 <str>ucsc_id</str>
 <str>lncrnadb</str>
 <str>enzyme_id</str>
 <str>uniprot_ids</str>
 <str>intermediate_filament_db</str>
 <str>ena</str>
 <str>ccds_id</str>
 <str>pubmed_id</str>
 <str>date_symbol_changed</str>
 </arr>
 </doc>
 </result>
</response>
fetch

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:

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

http://rest.genenames.org/fetch/alias_name/%22A-kinase%20anchor%20protein,%20350kDa%22

Below are examples of a JSON and an XML response:

JSON output

{
 "responseHeader":{
 "status":0,
 "QTime":0
 },
 "response":{
 "numFound":1,
 "start":0,
 "docs":[
 {
 "hgnc_id":"HGNC:13089",
 "symbol":"ZNF3",
 "name":"zinc finger protein 3",
 "status":"Approved",
 "locus_type":"gene with protein product",
 "prev_name":[
 "zinc finger protein 3 (A8-51)"
 ],
 "alias_symbol":[
 "A8-51",
 "KOX25",
 "PP838",
 "FLJ20216",
 "HF.12",
 "Zfp113"
 ],
 "location":"7q22.1",
 "date_approved_reserved":"1989-05-31T00:00:00Z",
 "date_modified":"2013-01-08T00:00:00Z",
 "date_name_changed":"2006-05-05T00:00:00Z",
 "ena":[
 "AF027136"
 ],
 "entrez_id":"7551",
 "mgd_id":[
 "MGI:1929116"
 ],
 "kznf_gene_catalog":460,
 "cosmic":"ZNF3",
 "refseq_accession":[
 "NM_017715"
 ],
 "gene_family":[
 "Zinc fingers, C2H2-type"
 ],
 "ensembl_gene_id":"ENSG00000166526",
 "ccds_id":[
 "CCDS43618",
 "CCDS43619"
 ],
 "locus_group":"protein-coding gene",
 "omim_id":194510,
 "uniprot_ids":[
 "P17036"
 ],
 "ucsc_id":"uc003usr",
 "rgd_id":[
 "RGD:6489147"
 ],
 "uuid":"9b6b4a19-a70f-4950-9a98-2431423a2a79",
 "_version_":1453576064268763138
 }
 ]
 }
}
XML output

<?xml version="1.0"?>
<response>
 <lst name="responseHeader">
 <int name="status">0</int>
 <int name="QTime">0</int>
 </lst>
 <result name="response" numFound="1" start="0">
 <doc>
 <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>
 <arr name="alias_symbol">
 <str>A8-51</str>
 <str>KOX25</str>
 <str>PP838</str>
 <str>FLJ20216</str>
 <str>HF.12</str>
 <str>Zfp113</str>
 </arr>
 <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>AF027136</str>
 </arr>
 <str name="entrez_id">7551</str>
 <arr name="mgd_id">
 <str>MGI:1929116</str>
 </arr>
 <int name="kznf_gene_catalog">460</int>
 <str name="cosmic">ZNF3</str>
 <arr name="refseq_accession">
 <str>NM_017715</str>
 </arr>
 <arr name="gene_family">
 <str>Zinc fingers, C2H2-type</str>
 </arr>
 <str name="ensembl_gene_id">ENSG00000166526</str>
 <arr name="ccds_id">
 <str>CCDS43618</str>
 <str>CCDS43619</str>
 </arr>
 <str name="locus_group">protein-coding gene</str>
 <int name="omim_id">194510</int>
 <arr name="uniprot_ids">
 <str>P17036</str>
 </arr>
 <str name="ucsc_id">uc003usr</str>
 <arr name="rgd_id">
 <str>RGD:6489147</str>
 </arr>
 <str name="uuid">e14b1f27-688c-48a3-ad48-bcb8b046ca27</str>
 <long name="_version_">1453576069925830657</long></doc>
 </result>
</response>
search

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:

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

{
 "responseHeader":{
 "status":0,
 "QTime":1
 },
 "response":{
 "numFound":2,
 "start":0,
 "maxScore":5.930616,
 "docs":[
 {
 "hgnc_id":"HGNC:7110",
 "symbol":"MKNK1",
 "score":5.930616
 },
 {
 "hgnc_id":"HGNC:7111",
 "symbol":"MKNK2",
 "score":5.930616
 }
 ]
 }
}
XML output

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

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.

alias_name
Other names used to refer to this gene as seen in the "SYNONYMS" field in the gene symbol report.
http://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 "SYNONYMS" field in the gene symbol report.
http://rest.genenames.org/search/alias_symbol/BRAF1
ccds_id
Consensus CDS ID. This field may be found within the "NUCLEOTIDE SEQUENCES" section of the gene symbol report.
http://rest.genenames.org/search/ccds_id/CCDS5863
ena
International Nucleotide Sequence Database Collaboration (GenBank, ENA and DDBJ) accession number(s). Found within the "NUCLEOTIDE SEQUENCES" section of the gene symbol report.
http://rest.genenames.org/search/ena/M95712
ensembl_gene_id
Ensembl gene ID. Found within the "GENE RESOURCES" section of the gene symbol report.
http://rest.genenames.org/search/ensembl_gene_id/ENSG00000157764
entrez_id
Entrez gene ID. Found within the "GENE RESOURCES" section of the gene symbol report.
http://rest.genenames.org/search/entrez_id/673
hgnc_id
HGNC ID. A unique ID created by the HGNC for every approved symbol.
http://rest.genenames.org/search/hgnc_id/1097
locus_group
A group name for a set of related locus types as defined by the HGNC (e.g. non-coding RNA).
http://rest.genenames.org/search/locus_group/\%22non-coding%20RNA%22
locus_type
The locus type as defined by the HGNC (e.g. RNA, transfer).
http://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.
http://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.
http://rest.genenames.org/search/name/%22zinc%20finger%20protein%20536%22
prev_name
Gene names previously approved by the HGNC for this gene. Equates to the "PREVIOUS SYMBOLS & NAMES" field within the gene symbol report.
http://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 & NAMES" field within the gene symbol report.
http://rest.genenames.org/search/prev_symbol/RN5S49
refseq_accession
RefSeq nucleotide accession. This field may be found within the "NUCLEOTIDE SEQUENCES" section of the gene symbol report.
http://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.
http://rest.genenames.org/search/rgd_id/%22RGD:2981%22
status
Status of the symbol report, which can be either "Approved" or "Entry Withdrawn".
http://rest.genenames.org/search/status/Approved
symbol
The HGNC approved gene symbol. Equates to the "APPROVED SYMBOL" field within the gene symbol report.
http://rest.genenames.org/search/symbol/KLF4
ucsc_id
UCSC gene ID. Found within the "GENE RESOURCES" section of the gene symbol report.
http://rest.genenames.org/search/ucsc_id/%22uc001rgp%22
uniprot_ids
UniProt protein accession. Found within the "PROTEIN RESOURCES" section of the gene symbol report.
http://rest.genenames.org/search/uniprot_ids/P00568
vega_id
Vega gene ID. Found within the "GENE RESOURCES" section of the gene symbol report.
http://rest.genenames.org/search/vega_id/OTTHUMG00000020722

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.

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
http://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>
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
http://www.ebi.ac.uk/ena/data/view/<ENA ACCESSION>
ensembl_gene_id (string)
See ensembl_gene_id within the searchable fields for the definition
http://www.ensembl.org/Homo_sapiens/Gene/Summary?g=<ENSEMBL GENE ID>
entrez_id (string)
See entrez_id within the searchable fields for the definition
http://www.ncbi.nlm.nih.gov/gene/<ID>
enzyme_id (string array)
ENZYME EC accession number
http://enzyme.expasy.org/EC/<EC ACCESSION NUMBER>
gene_family (string array)
HGNC gene family names to which the gene belongs.
gene_family_id (int array)
HGNC gene family ID to which the gene belongs.
http://www.genenames.org/cgi-bin/genefamilies/set/<ID>
hgnc_id (string)
See hgnc_id within the searchable fields for the definition
http://www.genenames.org/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>
kznf_gene_catalog (int)
ID used to link to the Human KZNF Gene Catalog
http://znf.igb.uiuc.edu/human/action/exploreView?type=locus&id=<ID>
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>
merops (string)
ID used to link to the MEROPS peptidase database
http://merops.sanger.ac.uk/cgi-bin/pepsum?mid=<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
http://www.ncbi.nlm.nih.gov/pubmed/<PMID> and http://europepmc.org/search/?page=1&query=<PMID>
refseq_accession (string array)
See refseq_accession within the searchable fields for the definition
http://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
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
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. 

 

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

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.

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

use HTTP::Tiny;
use JSON;
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 $result = decode_json($response->{content});
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 = 'http://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='http://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