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 manifestUrl and downloadBaseUrl. 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 downloadBaseUrl + 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$manifestUrl)

row <- subset(manifest$files,
              scope == "bulk" & resolution == "full_field" & format == "json")
df <- jsonlite::fromJSON(gzcon(url(file.path(meta$downloadBaseUrl, 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 '.downloadBaseUrl')/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!]
alleleExactMatch
Boolean
= true
serotypes
[String!]
scores
[String!]
antigens
[String!]
broadAntigens
[String!]
bw4_bw6
[String!]
resolution
Resolution
= two_field
accepts values: two_field or full_field

Response

locus
String
allele
String
score
String
serotype
String
antigen
String
broadAntigen
String
ciwd3
String
cwd2
String
eurcwd
String
bw4_bw6
String
version
String

Example Query

query {
  alleleToSerotype(
    alleles: ["A*02:01"]
    resolution: two_field
  ) {
    locus
    allele
    score
    serotype
    antigen
    broadAntigen
    bw4_bw6
    ciwd3
    cwd2
    eurcwd
    version
  }
}

Example Response

{
  "data": {
    "alleleToSerotype": [
      {
        "locus": "A",
        "allele": "A*02:01",
        "score": "FULL",
        "serotype": "A0201",
        "antigen": "A2",
        "broadAntigen": "A2",
        "bw4_bw6": "",
        "ciwd3": "C",
        "cwd2": "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