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 'Origin: https://growth.rcpch.ac.uk/' \
--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 'Origin: https://growth.rcpch.ac.uk/' \
--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"
    ]
  }
}

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.