Skip to content

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:

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"]
}'

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",
    "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"]
}' | 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 unparseable dates will log as errors.

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.

Run in Postman

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.