HLA Serotype Database

HLA Serotype

HomeIntroViewToolsAPIDownloadsAboutLogin

API

A GraphQL based API (Application Programming Interface) can be used to query the HLA Serotype Database.

How GraphQL APIs Work

Your App

GraphQL Query

GraphQL API

JSON Response

Serotype Data

An API (Application Programming Interface) defines a set of rules and protocols that enable different software applications to interact with one another. GraphQL is a query language designed for APIs that not only lets you retrieve data but also lets you specify exactly which data fields should be returned. This targeted approach ensures you obtain precisely the information you need in an efficient manner.

API Endpoint

https://serotype.org/api/graphql

Header (key:value)

x-api-key:

YOUR_API_KEY

Response size cap

Fetching bulk data in R or curl

Every response from /api/latest-version includes manifest_url and download_base_url. The manifest's files array enumerates every pre-built file with its scope, locus, resolution, and format. Pick the row you want, build the URL from download_base_url + path, fetch it. No API key required.

# R — pull bulk full-field for the current version
meta <- jsonlite::fromJSON("https://www.serotype.org/api/latest-version")
manifest <- jsonlite::fromJSON(meta$manifest_url)

row <- subset(manifest$files,
              scope == "bulk" & resolution == "full_field" & format == "json")
df <- jsonlite::fromJSON(gzcon(url(file.path(meta$download_base_url, row$path))))
cat("rows:", nrow(df), "for HATS", meta$version, "\n")
# curl — same file
META=$(curl -s https://www.serotype.org/api/latest-version)
URL=$(echo "$META" | jq -r '.download_base_url')/bulk/all_full.json.gz
curl -sL "$URL" | gunzip -c | jq '. | length'

See lesson 3 for a walk-through of all three patterns for bulk data (query narrowing, cap-error handling, manifest-driven discovery).

Parameters

loci
[String!]
alleles
[String!]
allele_exact_match
Boolean
= true
serotypes
[String!]
scores
[String!]
split_antigens
[String!]
broad_antigens
[String!]
bw4_bw6
[String!]
resolution
Resolution
= two_field
accepts values: two_field or full_field

Response

locus
String
allele
String
score
String
score_code
String
score_description
String
serotype
String
split_antigen
String
broad_antigen
String
ciwd
String
cwd
String
eurcwd
String
bw4_bw6
String
version
String

Example Query

query {
  alleleToSerotype(
    alleles: ["A*02:01"]
    resolution: two_field
  ) {
    locus
    allele
    score
    score_code
    score_description
    serotype
    split_antigen
    broad_antigen
    bw4_bw6
    ciwd
    cwd
    eurcwd
    version
  }
}

Example Response

{
  "data": {
    "alleleToSerotype": [
      {
        "locus": "A",
        "allele": "A*02:01",
        "score": "Full",
        "score_code": "F",
        "score_description": "Matches the serotype's reference pattern at every defining residue.",
        "serotype": "A0201",
        "split_antigen": "A2",
        "broad_antigen": "A2",
        "bw4_bw6": "",
        "ciwd": "C",
        "cwd": "C",
        "eurcwd": "C",
        "version": "1.0"
      }
    ]
  }
}

Deep links to detail pages

Separate from the GraphQL API, every serotype and allele has a stable, shareable detail page. External sites can link straight to them, no API key needed, as these are public pages.

Serotype

https://serotype.org/sero/{serotype}

# example
https://serotype.org/sero/A0201

Lookups are case- and hyphen-insensitive, so /sero/A-0201 resolves to the same page as /sero/A0201.

Allele

https://serotype.org/allele/{allele}

# two-field
https://serotype.org/allele/A*02:01

# full-field
https://serotype.org/allele/A*02:01:01:01

The colon (:) may be used literally in the path. If your tooling requires it, percent-encoding the colon as %3A (e.g. /allele/A*02%3A01) also resolves to the same page.

Names are matched case-insensitively. Unknown names render a “not found” page rather than an error.

See the API in action using interactive tools that can generate the GraphQL query and return the results. Try it now

Learn how to use the API with interactive R examples at our learning portal