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",
    "ambiguous",
    "locus_group",
    "alias_symbol",
    "_version_",
    "uuid",
    "prev_name",
    "refseq_accession",
    "mirbase",
    "lsdb",
    "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>ambiguous</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>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":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>
      <int name="hgnc_id">13089</int>
      <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>
      <int name="entrez_id">7551</int>
      <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":7110,
        "symbol":"MKNK1",
        "score":5.930616
      },
      {
        "hgnc_id":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>
    <int name="hgnc_id">7110</int>
    <str name="symbol">MKNK1</str>
    <float name="score">5.930616</float></doc>
  <doc>
    <int name="hgnc_id">7111</int>
    <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
The synonymous name for the gene as seen in the "SYNONYMS" field in the gene symbol report. The alias name is the alternative names that has been used to refer to the gene within certain literature texts or from other databases.
http://rest.genenames.org/search/alias_name/%22A-kinase%20anchor%20protein,%20350kDa%22


alias_symbol
The synonymous symbol for the gene as seen in the "SYNONYMS" field in the gene symbol report. The alias symbol may have been refered to within certain literature texts or from other databases.
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
European Nucleotide Archive (ENA) accession number. 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. This is a stable ID given to a gene which will not change even if the gene symbol or name changes.
http://rest.genenames.org/search/hgnc_id/1097


locus_group
A group name for a set of similar locus types as set by the HGNC.
http://rest.genenames.org/search/locus_group/\%22non-coding%20RNA%22


locus_type
The locus type as set by the HGNC.
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
A previous HGNC approved but replaced gene name. 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
A previous HGNC approved but replaced gene symbol. 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
HGNC status for gene symbol reports the values of which will either be "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
See alias_name within the searchable fields for the definition


alias_symbol
See alias_symbol within the searchable fields for the definition


bioparadigms_slc
Symbol used to link to the SLC tables database at bioparadigms.org for the gene
http://slc.bioparadigms.org/protein?GeneName=<SYMBOL>


ccds_id
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
Symbol used within the Human Cell Differentiation Molecule database for the gene
http://www.hcdm.org/index.php?option=com_molecule&cdnumber=<SYMBOL>


cosmic
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
The date the gene entry was approved or reserved.


date_modified
Date the entry was last modified.


date_name_changed
The date the gene name was last changed.


date_symbol_changed
The date the gene symbol was last changed.


ena
See ena within the searchable fields for the definition
http://www.ebi.ac.uk/ena/data/view/<ENA ACCESSION>


ensembl_gene_id
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
See entrez_id within the searchable fields for the definition
http://www.ncbi.nlm.nih.gov/gene/<ID>


enzyme_id
ENZYME EC accession number
http://enzyme.expasy.org/EC/<EC ACCESSION NUMBER>


hgnc_id
See hgnc_id within the searchable fields for the definition
http://dev.genenames.org/data/gene_symbol_report?hgnc_id=<HGNC ID>


homeodb
Homeobox Database ID
http://homeodb.cbi.pku.edu.cn/gene_info.get?id=<ID>


horde_id
Symbol used within HORDE for the gene
http://genome.weizmann.ac.il/horde/card/index/symbol:<SYMBOL>


imgt
Symbol used within international ImMunoGeneTics information system
http://www.imgt.org/IMGT_GENE-DB/GENElect?query=2+<SYMBOL>&species=Homo+sapiens


intermediate_filament_db
ID used to link to the Human Intermediate Filament Database
http://www.interfil.org/details.php?id=<ID>


iuphar
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
ID used to link to the Human KZNF Gene Catalog
http://znf.igb.uiuc.edu/human/action/exploreView?type=locus&id=<ID>


lncrnadb
lncRNA Database ID
http://www.lncrnadb.org/Detail.aspx?TKeyID=<ID>


location
Cytogenetic location of the gene (eg 2q34).


locus_group
See locus_group within the searchable fields for the definition


locus_type
See locus_type within the searchable fields for the definition


lsdb
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
ID to link to the Mamit-tRNA database
http://mamit-trna.u-strasbg.fr/mutations.asp?idAA=<ID>


merops
ID used to link to the MEROPS peptidase database
http://merops.sanger.ac.uk/cgi-bin/pepsum?mid=<ID>


mgd_id
See mgd_id within the searchable fields for the definition
http://www.informatics.jax.org/marker/<MGD ID>


mirbase
miRBase ID
http://www.mirbase.org/cgi-bin/mirna_entry.pl?acc=<ID>


name
See name within the searchable fields for the definition


omim_id
Online Mendelian Inheritance in Man (OMIM) ID
http://www.omim.org/entry/<ID>


orphanet
Orphanet ID
http://www.orpha.net/consor/cgi-bin/OC_Exp.php?Lng=GB&Expert=<ID>


prev_name
See prev_name within the searchable fields for the definition


prev_symbol
See prev_symbol within the searchable fields for the definition


pseudogene.org
Pseudogene.org ID
http://tables.pseudogene.org/<ID>


pubmed_id
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
See refseq_accession within the searchable fields for the definition
http://www.ncbi.nlm.nih.gov/nuccore/<REFSEQ ACCESSION>


rgd_id
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
snoRNABase ID
https://www-snorna.biotoul.fr//plus.php?snoid=<ID>


status
See status within the searchable fields for the definition


symbol
See symbol within the searchable fields for the definition


ucsc_id
See ucsc_id within the searchable fields for the definition


uniprot_ids
See uniprot_ids within the searchable fields for the definition
http://www.uniprot.org/uniprot/<UNIPROT ID>


uuid
Unique ID held within the search server


vega_id
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