Making calls to the Digital Growth Charts API¶

There are as many ways to make an API call as there are software developers, but here are some common ways. We'll start by using cURL to get you started but if you prefer a graphical tool, then feel free to skip ahead to the Postman section.

API baseURL

For all API calls to the Growth Charts API, you should use the baseURL

https://api.rcpch.ac.uk/growth/v1

path: Our API path naming policy (growth) is designed to allow the same baseUrl to be used for other APIs in the future.
versioning: We have versioned the API v1 to allow for future versions to be developed without interfering with existing integrations.
relative: All API requests should be made to this URL, and the endpoints described in the API definition are relative to this base URL.
authentication: The API will return Unauthorized or Not Found (4xx) responses if the request does not include a valid API key.

cURL¶

cURL is a very simple and common tool for making web requests from the command line (also known as the 'terminal' or 'command prompt'). Official documentation for cURL can be found here.

Installing cURL¶

Download cURL here. Scroll to the correction download for your Operating System.

Windows download, install, and usage

For Windows, please see this guide on how to download and install cURL.

Use the Git Bash command line to save headaches regarding formatting.

Using cURL to make a test request¶

Copy and paste the following cURL request into your command line, inserting your Primary key. This example sends only the required parameters - that is all you need to get a centile result back. Optional parameters such as bone age and events are covered in Optional parameters and advanced features below. Use the tab that matches your operating system - the macOS / Linux version uses Bash quoting and \ line continuations, while the Windows version uses Command Prompt quoting and ^ line continuations.

macOS / Linux Windows

curl --location --request POST 'https://api.rcpch.ac.uk/growth/v1/uk-who/calculation' \
--header 'Subscription-Key: YOUR_PRIMARY_API_KEY_GOES_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
    "birth_date": "2020-04-12",
    "observation_date": "2028-06-12",
    "observation_value": 115,
    "sex": "female",
    "gestation_weeks": 40,
    "gestation_days": 0,
    "measurement_method": "height"
}'

Windows Command Prompt and PowerShell do not understand Bash's \ line continuations or single-quoted JSON, so the macOS / Linux example will fail if pasted as-is. The version below uses ^ for line continuation and escapes the inner double quotes (\") so the JSON survives Command Prompt's quoting rules. cURL ships with Windows 10 and later.

curl --location --request POST "https://api.rcpch.ac.uk/growth/v1/uk-who/calculation" ^
--header "Subscription-Key: YOUR_PRIMARY_API_KEY_GOES_HERE" ^
--header "Content-Type: application/json" ^
--data-raw "{\"birth_date\": \"2020-04-12\", \"observation_date\": \"2028-06-12\", \"observation_value\": 115, \"sex\": \"female\", \"gestation_weeks\": 40, \"gestation_days\": 0, \"measurement_method\": \"height\"}"

Using PowerShell?

In PowerShell, curl is an alias for Invoke-WebRequest, which has different syntax. Call curl.exe explicitly to use real cURL, or simply run the command in Command Prompt instead.

The response should be a large JSON response like the following (truncated):

{"birth_data":{"birth_date":"2020-04-12", ... :{"events_text":["Growth hormone start","Growth Hormone Deficiency diagnosis"]}}

jq

A neat tool for pretty-printing JSON in the command line is jq. With jq installed, you can pipe the cURL output to jq and get a much easier-to-read response:

curl --location --request POST 'https://api.rcpch.ac.uk/growth/v1/uk-who/calculation' \
--header 'Subscription-Key: YOUR_PRIMARY_API_KEY_GOES_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
    "birth_date": "2020-04-12",
    "observation_date": "2028-06-12",
    "observation_value": 115,
    "sex": "female",
    "gestation_weeks": 40,
    "gestation_days": 0,
    "measurement_method": "height"
}' | jq

You should get a nicely formatted JSON response object:

{
  "birth_data": {
    "birth_date": "2020-04-12",
    "gestation_weeks": 40,
... # truncated
    "events_text": [
        "Growth hormone start",
        "Growth Hormone Deficiency diagnosis"
    ]
  }
}

A note about dates¶

The response object from the API contains dates without times in the format YYYY-MM-DD. This is the format that the digital growth charts react component library expects. If the output of the API is passed directly to the charts they will render the measurements automatically. RCPCH recommend that the response is persisted, so that an API call is only required for each new measurement.

If in the process of serializing or deserializing the response, the date format is changed, RCPCH advise ensuring that the dates do not change format. In case this happens, the charting component is optimized to process common date types, but will log this as a warning in the console. Any un-parseable dates will log as errors.

Optional parameters and advanced features¶

The test request above sends only the parameters the API needs to return a centile result:

Required parameter	Description
`birth_date`	The child's date of birth (`YYYY-MM-DD`).
`observation_date`	The date the measurement was taken (`YYYY-MM-DD`).
`observation_value`	The measurement value (e.g. height in cm, weight in kg).
`sex`	`male` or `female`.
`gestation_weeks`	Completed weeks of gestation at birth (use `40` for a term baby).
`gestation_days`	Additional days of gestation at birth (use `0` for a term baby).
`measurement_method`	`height`, `weight`, `ofc` (head circumference), or `bmi`.

Gestational age is fixed at birth - never change it between measurements

gestation_weeks and gestation_days describe how far through pregnancy the child had reached when they were born - for example, a baby born five weeks early is 35 weeks and 0 days, and a baby born on their due date is 40 weeks and 0 days.

Gestational age is a fixed fact about the individual. It is determined at the moment of birth and does not change for the rest of that child's life. Every measurement you send for the same child must use the same gestation_weeks and gestation_days.

The API uses these values to calculate the child's corrected age (their age adjusted for prematurity), which is what allows a preterm baby to be plotted fairly against the growth reference. If you send different gestation values for different measurements of the same child, each measurement is corrected differently, and plotting them together produces a misleading growth trajectory. Store the gestation once against the patient record and reuse it for every measurement.

Everything else is optional. You do not need to send any of the following to get a valid result, and most measurements will not use them. They unlock additional features when you need them:

Bone age

Bone age is a specialist radiological measurement, usually only performed for a very small minority of children seen in a growth or endocrine clinic. If you send the bone age parameters (bone_age, bone_age_centile, bone_age_sds, bone_age_text, bone_age_type), the API simply returns them alongside the growth data so the chart component can plot them. The API does not calculate bone age for you.

Events

events_text lets you attach clinical annotations (for example "Growth hormone start") to a measurement. The API passes these straight back in the response so the chart component can display them as event markers against the relevant point. They are purely for annotation and do not affect the centile calculation.

Down syndrome and Turner syndrome

To plot against the condition-specific references, call the matching endpoint instead of uk-who - for example /growth/v1/trisomy-21/calculation or /growth/v1/turner/calculation. See Turner and Down Syndrome for details.

Other (non-UK-WHO) references

The same calculation request can be sent to other reference endpoints, such as the CDC (US) reference, by changing the reference segment of the URL. The request body stays the same.

Below is the same request as before, this time including the optional bone age and events parameters:

curl --location --request POST 'https://api.rcpch.ac.uk/growth/v1/uk-who/calculation' \
--header 'Subscription-Key: YOUR_PRIMARY_API_KEY_GOES_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
    "birth_date": "2020-04-12",
    "observation_date": "2028-06-12",
    "observation_value": 115,
    "sex": "female",
    "gestation_weeks": 40,
    "gestation_days": 0,
    "measurement_method": "height",
    "bone_age": 10,
    "bone_age_centile": 98,
    "bone_age_sds": 2.0,
    "bone_age_text": "This bone age is advanced",
    "bone_age_type": "greulich-pyle",
    "events_text": ["Growth hormone start", "Growth Hormone Deficiency diagnosis"]
}'

Postman ¶

Postman is a tool for API development. The RCPCH team used Postman extensively during the API development and testing process. Download Postman here.

We have produced a set of Postman Collections and Environments which can help you explore the dGC API.

openAPI3 (Swagger) API documentation ¶

As we've specified our API documentation in the openAPI3 (formerly known as 'Swagger') format, we can auto-generate API documentation.

The Swagger API reference is here.