JSON API

Philipp Bayer edited this page Aug 4, 2014 · 8 revisions

This page is split up into three parts: Information on users, information on phenotypes and information on SNPs. The entire API is still a work-in-progress, in some way it's inconsistent so over time we'll insert some more consistent paths while keeping the old ones available.

The API returns data in the popular JSON-format, so use Python's "json"-package or Ruby's "json"-gem to read the data. If you want to have a quick overview of the resulting JSON-object you can use various online parsers, like this JSON parser.

Note: This page is still under construction, you may imagine one of these spinning construction-site gifs from the 90s here.

Users & Genotypes

There are several ways to access information on a user (or a range of users).

Get all users

Use the following call to get a list of all openSNP users:

http://opensnp.org/users.json

This returns an array of users. Each item of the array includes the following attributes:

  • name: The users name
  • id: The user ID which can be used for further calls on phenotypes and genotypes
  • genotypes: An array on the genotyping files this user has uploaded. Each genotype item has it's own attributes:
  1. id: The ID of the genotyping file
  2. filetype: the filetype of the genotyping file, e.g. 23andme
  3. download_url: The URL where the genotyping file can be downloaded

Get all users who share a certain SNP, example for SNP with the name rs7903146

http://opensnp.org/snps/rs7903146.json

This returns an array which includes the genotypes of all users at this SNP. Each item in the array has two main objects:

  1. snp: This object has three attributes: name, the name of the SNP, chromosome, the chromosome the SNP is located on, position, the position of the SNP, relative to the NCBI36 build of the human genome.
  2. user: The object includes all the users name, his genotype at this SNP and the users id

Get only a subset of these users:

http://opensnp.org/snps/json/rs7903146/1-8.json

This will give you the genotypes for rs7903146 for the user-IDs 1 to 8. If one of the users doesn't have any genotype information available the item in the array will only have error as a key. Otherwise the object will have the same items as recorded above.

Get only a subset of certain user(-ID)s:

http://opensnp.org/snps/json/rs7903146/1,6,8.json

This will give you the genotypes for the same SNP for user-IDs 1, 6 and 8. The return object works analog to Get only a subset of these users

SNPs & Annotation

Get all SNPedia/PLos/Mendeley-annotations for a specific SNP

http://opensnp.org/snps/json/annotation/rs7903146.json

This returns a snp object which gives basic details for a SNP and the annotation we have listed for it. The attributes of the SNP object are:

  • name: The name of the SNP
  • chromosome: The chromosome the SNP is located on
  • position: The position of the SNP, relative to the NCBI36 build of the human genome
  • genotype_frequency: A hash with genotype frequencies, as in: {"CC":869,"CT":631,"TT":142}
  • allele_frequency: A hash with allele frequencies, as in: {"A":0,"T":915,"G":0,"C":2369}
  • annotations: A hash which has 3 keys: mendeley, plos and snpedia. The value for each hash is an array of annotation-objects.

You can do the same thing for several SNPs:

   http://opensnp.org/snps/json/annotation/rs7903146,rs9939609.json

This will return two objects with the same attributes to above, but instead of the object being named snp the object has the name of the SNP in question.

Attributes for the mendeley objects:

  • author: First Author of the paper
  • title: The title of the paper
  • publication_year: the year in which the publication was made public
  • number_of_readers: The number of readers the publication has on Mendeley
  • open_access: Whether the publication is published as Open Access, can be true or false
  • url: The URL to the publication on Mendeley
  • doi: Either the DOI of the publication or none

Attributes for the plos objects:

  • author: First Author of the paper
  • title: The title of the paper
  • publication_date: the data on in which the publication was released in PLOS
  • number_of_readers: The number of readers the publication has on PLOS
  • url: The URL to the publication
  • doi: Either the DOI of the publication

Attributes for the snpedia objects:

  • url: URL to the annotation on SNPedia
  • summary: The summary of the SNPedia annotation

Phenotypes

Get all phenotypes entered

http://opensnp.org/phenotypes.json

This returns an array of all phenotypes. Each phenotype has the following attributes:

  • id: The phenotype-ID which can be used for further calls
  • characteristic: Which trait this phenotype asks for
  • known_variations: An array of all the variations users have entered so far
  • number_of_users: How many users of openSNP have entered their variation on this phenotype so far

Get all known variations and all users sharing that phenotype for one phenotype(-ID)

http://opensnp.org/phenotypes/json/variations/12.json

Returns extensive information about a single phenotype. The results include the following attributes:

  • id: The ID of the phenotype
  • characteristic: Which trait this phenotype asks for
  • description: A longer description of this phenotype
  • known_variation: An array of all the variations users have entered so far
  • users: A array of users which have entered their variation and the variation they have entered.

Each item in the users-array includes:

  • user_id: The users ID
  • variation: The variation this user has entered for this phenotype

Get all phenotypes from a specific user(-ID)

http://opensnp.org/phenotypes/json/1.json

Returns some details on the user as well as all his phenotypic variations. The result includes:

  • user: This object has two attributes: The name of the user and the id of the user
  • phenotypes: This object is a hash which includes the name of each phenotype as key and the phenotype_id and the phenotypic variation of this user at the requested phenotype.

Get all phenotypes for a range of user-IDs

http://opensnp.org/phenotypes/json/1-10.json

Returns an array of objects as described in Get all phenotypes from a specific user(-ID). Missing phenotypes are represented by including error as a key in the phenotypes hash.

Get all phenotypes for certain user(ID)s 1, 3 and 10

http://opensnp.org/phenotypes/json/1,3,10.json

Works analogous to Get all phenotypes for a range of user-IDs

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.