openapi: 3.0.0
servers:
  - url: ""
info:
  contact:
    x-twitter: amentumspace
  description: |
    Our atmosphere protects us from a hostile space radiation environment comprising high energy particles of solar and intergalactic origin. Solar radiation is significant during unpredictable and short lived solar flares and coronal mass ejections (CMEs); however, galactic cosmic radiation (GCR) is omnipresent. The GCR intensity varies with latitude, longitude, and time due to effects of solar activity on the interplanetary magnetic field, as well as the Earth's magnetic field. Space radiation collides with gases in the atmosphere, leading to a complex shower of high energy radiation, the intensity and composition of which varies spatially and temporally. Excessive exposure to radiation can damage DNA and lead to long-term health effects such as an increased risk of cancer.  <br><br> Resulting radiation levels at commercial aircraft altitudes are greater than at sea level. Aircrew are classified as radiation workers in some countries; however, planning to limit their exposure, and monitoring, is generally lacking. Both real-time measurements and predictive models of radiation in the atmosphere are important to mitigate the radiation risk to crew. <br><br>
    We host a RESTful API to models of cosmic ray induced ionising radiation in the atmosphere. 
    The CARI7 and PARMA endpoints use models developed by the US Federal Aviation Administration and the Japan Atomic Energy Agency to  calculate cosmic radiation doses at a point. 
    The Route Dose API calculates the same quantities along a great circle route between two airports using CARI7. <br><br>
    API requests must contain a key "API-Key" in the header (see code samples). Obtain a key from  <a href='https://developer.amentum.io'>here</a>. <br><br> 
    Help us improve the quality of our web APIs by completing our 2 minute survey <a href="https://www.surveymonkey.com/r/CTDTRBN">here</a>.<br><br>
    Amentum Pty Ltd is not responsible nor liable for any loss or damage of any sort incurred as a result of using the API. <br><br>
    Copyright <a href='https://amentum.space'>Amentum Pty Ltd</a> 2022.
  title: Aviation Radiation API
  version: 1.5.0
  x-apisguru-categories:
    - location
    - open_data
  x-logo:
    altText: Amentum Aerospace
    backgroundColor: "#FFFFFF"
    url: https://twitter.com/amentumspace/profile_image?size=original
  x-origin:
    - format: openapi
      url: https://cosmicrays.amentum.space//openapi.json
      version: "3.0"
  x-providerName: amentum.space
  x-serviceName: aviation_radiation
tags:
  - description: |
      Developed by the US Federal Aviation Administration's  Civil Aerospace Medical Institute, CARI7 calculates cosmic  ray doses in the atmosphere. See <a href="https://academic.oup.com/rpd/article/175/4/419/2884614">here</a> for a complete description of  CARI-7. The original source code and Terms and Conditions can be found <a href="https://www.faa.gov/data_research/research/med_humanfacs/aeromedical/radiobiology/cari7/">here</a><br><br> <br><br> Note: The dose is considered a monthly average. It accounts for for heliocentric potential modulation only, minor geomagnetic storm and forbush decreases are ignored.
    name: cari7
    x-displayName: CARI7 API
  - description: |
      The Route Dose API estimates radiation doses along a flight route between two airports with known ICAO or IATA codes or coordinates as latitude/longitude. Waypoints are calculated assuming a great circle  route, and either a constant altitude (in kilometers) and a flight duration (in hours) or lists of altitudes and cruising times to define a step climb.  Dose rates are then calculated at each waypoint using CARI-7.  The dose rate profile is integrated along the route to obtain the total dose for the flight. <br><br> Note: Dose is considered a monthly average accounting for heliocentric potential (HP) modulation only, minor geomagnetic storm and forbush decrease corrections are ignored. The calculation relies on HP data from the US Federal Aviation Administration that is released monthly. Doses can be calculated on the current date and short-range forecasting  of several weeks is supported (the exact forecast horizon depends on the release date of the FAA data).
    name: routedose
    x-displayName: Route Dose API
  - description: |
      The PARMA model was developed by the Japan Atomic Energy Agency (JAEA) and estimates fluxes of neutrons, protons, ions, muons, electrons, positrons, and photons on a given date, latitude, longitude, and altitude. A comprehensive description of PARMA can be found in the publications <a href="https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0160390">here</a> and <a href="https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0144679">here</a>.<br><br> <br><br> Note: the PARMA API only accounts for heliocentric potential modulation, minor geomagnetic storm and forbush decreases are ignored.
    name: parma
    x-displayName: PARMA API
paths:
  /cari7/ambient_dose:
    get:
      description: |
        The ambient dose equivalent, H*(10), is an operational quantity that simulates the  human body by measuring the dose equivalent at a depth of 10 mm within a tissue  equivalent sphere of 300 mm diameter. It is a measurable quantity that is  used to calibrate area monitors (radiation detectors) for mixed radiation fields. 
        Use this endpoint if you are comparing model predictions to measurements.
      operationId: app.api_cari7.endpoints.CARI7.ambient_dose
      parameters:
        - description: Altitude (in km). The minimum is 0 m, the maximum is 47 km (the upper limit of the stratosphere).
          in: query
          name: altitude
          required: true
          schema:
            example: 11
            type: number
        - description: Latitude. -90 (S) to 90 (N).
          in: query
          name: latitude
          required: true
          schema:
            example: 30
            type: number
        - description: Longitude. -180 (W) to 180 (E).
          in: query
          name: longitude
          required: true
          schema:
            example: 30
            type: number
        - description: Year in YYYY.
          in: query
          name: year
          required: true
          schema:
            example: 2019
            type: integer
        - description: Month in MM.
          in: query
          name: month
          required: true
          schema:
            example: 12
            type: integer
        - description: Day in DD.
          in: query
          name: day
          required: true
          schema:
            example: 1
            type: integer
        - description: Hour in 24 hour time.
          in: query
          name: utc
          required: true
          schema:
            example: 3
            type: integer
        - description: |
            The particle type as a string. Specifying 'total' returns the dose for all particle types.
          in: query
          name: particle
          required: true
          schema:
            enum:
              - total
              - neutron
              - photon
              - e-
              - e+
              - mu-
              - mu+
              - proton
              - pi-
              - pi+
              - deuteron
              - triton
              - helion
              - alpha
              - Li
              - Be
              - B
              - C
              - N
              - O
              - F
              - Ne
              - Na
              - Mg
              - Al
              - Si
              - P
              - S
              - Cl
              - Ar
              - K
              - Ca
              - Sc
              - Ti
              - V
              - Cr
              - Mn
              - Fe
            example: total
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                example:
                  dose rate:
                    units: uSv/hr
                    value: 2.322303291477743
                properties:
                  dose rate:
                    properties:
                      units:
                        type: string
                      value:
                        type: number
                    type: object
                type: object
          description: Successful dose calculation
      summary: |
        The ambient dose equivalent rate calculated for a single particle type, or accumulated over all particle types.
      tags:
        - cari7
      x-codeSamples:
        - lang: Shell
          source: |
            curl -X GET "https://avrad.amentum.io/cari7/ambient_dose?altitude=11&latitude=30&longitude=30&year=2019&month=12&day=1&utc=3&particle=total" -H "API-Key: <your_key>" -H "accept: application/json"
        - lang: Python
          source: |
            import requests

            params = {
                "altitude" : 11, #km 
                "latitude" : 30, #degrees (N)
                "longitude" : 30, #degrees (E)
                "year" : 2019,  
                "month" : 12,
                "day" : 1,
                "particle" : "total",
                "utc" : 3
            }
            headers = {"API-Key" : "<add_your_key>"}
            url = "https://avrad.amentum.io/cari7/ambient_dose"
            try:
                response = requests.get(url, params=params, headers=headers) 
                response.raise_for_status()
            except requests.exceptions.HTTPError as e: 
                print("HTTP error", e)
            except requests.exceptions.RequestException as e: 
                print("Request error", e)
            else:
                # retrieve and return the dose rate
                dose_rate = response.json() 
                dose_rate_val = dose_rate['dose rate']['value']
                units = dose_rate['dose rate']['units']

                print(f"Dose rate is {dose_rate_val} {units}")
        - lang: Javascript
          source: |
            let url = 'https://avrad.amentum.io/cari7/ambient_dose?'

            var params = new URLSearchParams({
                altitude : 11, // km 
                latitude : 30, // degrees (N)
                longitude : 30, // degrees (E)
                year : 2019,  
                month : 12,
                day : 1,
                particle : "total",
                utc : 3
            })

            var requestOptions = {
              method: 'GET',
              redirect: 'follow',
              headers: {'API-Key': '<add_your_key>'} 
            };

            fetch(url + params, requestOptions)
              .then(response => response.text())
              .then(result => console.log(result))
              .catch(error => console.log('error', error));
  /cari7/effective_dose:
    get:
      description: |
        Effective Dose is a radiation protection quantity defined by the International Commission on
         Radiological Protection (ICRP) and represents the stochastic health
         risk to the human body at low levels of radiation.
        It accounts for the different sensitivities of organs to ionising radiation, as well as the different effectiveness of various types of radiation.
        Use this endpoint if you need to estimate radiation exposures of personnel.
      operationId: app.api_cari7.endpoints.CARI7.effective_dose
      parameters:
        - description: Altitude (in km). The minimum is 0 m, the maximum is 47 km (the upper limit of the stratosphere).
          in: query
          name: altitude
          required: true
          schema:
            example: 11
            type: number
        - description: Latitude. -90 (S) to 90 (N).
          in: query
          name: latitude
          required: true
          schema:
            example: 30
            type: number
        - description: Longitude. -180 (W) to 180 (E).
          in: query
          name: longitude
          required: true
          schema:
            example: 30
            type: number
        - description: Year in YYYY.
          in: query
          name: year
          required: true
          schema:
            example: 2019
            type: integer
        - description: Month in MM.
          in: query
          name: month
          required: true
          schema:
            example: 12
            type: integer
        - description: Day in DD.
          in: query
          name: day
          required: true
          schema:
            example: 1
            type: integer
        - description: Hour in 24 hour time.
          in: query
          name: utc
          required: true
          schema:
            example: 3
            type: integer
        - description: |
            The particle type as a string. Specifying 'total' returns the dose for all particle types.
          in: query
          name: particle
          required: true
          schema:
            enum:
              - total
              - neutron
              - photon
              - e-
              - e+
              - mu-
              - mu+
              - proton
              - pi-
              - pi+
              - deuteron
              - triton
              - helion
              - alpha
              - Li
              - Be
              - B
              - C
              - N
              - O
              - F
              - Ne
              - Na
              - Mg
              - Al
              - Si
              - P
              - S
              - Cl
              - Ar
              - K
              - Ca
              - Sc
              - Ti
              - V
              - Cr
              - Mn
              - Fe
            example: total
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                example:
                  dose rate:
                    units: uSv/hr
                    value: 2.1532952875056712
                properties:
                  dose rate:
                    properties:
                      units:
                        type: string
                      value:
                        type: number
                    type: object
                type: object
          description: Successful dose calculation
      summary: |
        The effective dose rate calculated for a single particle type, or accumulated over all particle types.
      tags:
        - cari7
      x-codeSamples:
        - lang: Shell
          source: |
            curl -X GET "https://avrad.amentum.io/cari7/effective_dose?altitude=11&latitude=30&longitude=30&year=2019&month=12&day=1&utc=3&particle=total" -H "API-Key: <your_key>" -H "accept: application/json"
        - lang: Python
          source: |
            import requests

            params = {
                "altitude" : 11, #km 
                "latitude" : 30, #degrees (N)
                "longitude" : 30, #degrees (E)
                "year" : 2019,  
                "month" : 12,
                "day" : 1,
                "particle" : "total",
                "utc" : 3
            }
            headers = {"API-Key" : "<add_your_key>"}
            url = "https://avrad.amentum.io/cari7/effective_dose"
            try:
                response = requests.get(url, params=params, headers=headers) 
                response.raise_for_status()
            except requests.exceptions.HTTPError as e: 
                print("HTTP error", e)
            except requests.exceptions.RequestException as e: 
                print("Request error", e)
            else:
                # retrieve and return the dose rate
                dose_rate = response.json() 
                dose_rate_val = dose_rate['dose rate']['value']
                units = dose_rate['dose rate']['units']

                print(f"Dose rate is {dose_rate_val} {units}")
        - lang: Javascript
          source: |
            let url = 'https://avrad.amentum.io/cari7/effective_dose?'

            var params = new URLSearchParams({
                altitude : 11, // km 
                latitude : 30, // degrees (N)
                longitude : 30, // degrees (E)
                year : 2019,  
                month : 12,
                day : 1,
                particle : "total",
                utc : 3
            })

            var requestOptions = {
              method: 'GET',
              redirect: 'follow',
              headers: {'API-Key': '<add_your_key>'} 
            };

            fetch(url + params, requestOptions)
              .then(response => response.text())
              .then(result => console.log(result))
              .catch(error => console.log('error', error));
  /parma/ambient_dose:
    get:
      description: |
        The ambient dose equivalent, H*(10), is an operational quantity that simulates the  human body by measuring the dose equivalent at a depth of 10 mm within a tissue  equivalent sphere of 300 mm diameter. It is a measurable quantity that is  used to calibrate area monitors (radiation detectors) for mixed radiation fields. 
        Use this endpoint if you are comparing model predictions to measurements.
      operationId: app.api_parma.endpoints.PARMA.ambient_dose
      parameters:
        - description: Altitude (in km). The minimum is 0 m, the maximum is 47 km (the upper limit of the stratosphere).
          in: query
          name: altitude
          required: false
          schema:
            example: 11
            type: number
        - description: |
            Atmospheric depth from the top of the atmosphere (in units of g/cm2). The minimum is 0.913 g/cm2, the maximum is 1032.66 g/cm2. WARNING: you can specify either altitude OR atmospheric depth, not both.
          in: query
          name: atmospheric_depth
          required: false
          schema:
            example: 0.92
            type: number
        - description: Latitude. -90 (S) to 90 (N).
          in: query
          name: latitude
          required: true
          schema:
            example: 30
            type: number
        - description: Longitude. -180 (W) to 180 (E).
          in: query
          name: longitude
          required: true
          schema:
            example: 30
            type: number
        - description: Year in YYYY.
          in: query
          name: year
          required: true
          schema:
            example: 2019
            type: integer
        - description: Month in MM.
          in: query
          name: month
          required: true
          schema:
            example: 12
            type: integer
        - description: Day in DD.
          in: query
          name: day
          required: true
          schema:
            example: 1
            type: integer
        - description: |
            The particle type as a string. Specifying 'total', only used for the dose calculation, returns the dose for all particle types.
          in: query
          name: particle
          required: true
          schema:
            enum:
              - total
              - e-
              - e+
              - mu+
              - mu-
              - gamma
              - neutron
              - proton
              - alpha
            example: proton
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                example:
                  dose rate:
                    units: uSv/hr
                    value: 0.26835067168474125
                properties:
                  dose rate:
                    properties:
                      units:
                        type: string
                      value:
                        type: number
                    type: object
                type: object
          description: Successful dose read operation
      summary: |
        The ambient dose equivalent rate calculated for a single particle type, or accumulated over all particle types.
      tags:
        - parma
      x-codeSamples:
        - lang: Shell
          source: |
            curl -X GET "https://avrad.amentum.io/parma/ambient_dose?altitude=11&latitude=30&longitude=30&year=2019&month=12&day=1&particle=proton" -H "API-Key: <your_key>" -H  "accept: application/json"
        - lang: Python
          source: |
            import requests

            params = {
                "altitude" : 11, #km 
                "latitude" : 30, #degrees (N)
                "longitude" : 30, #degrees (E)
                "year" : 2019,  
                "month" : 12,
                "day" : 1,
                "particle" : "proton"
            }
            headers = {"API-Key" : "<add_your_key>"}
            url = "https://avrad.amentum.io/parma/ambient_dose"
            try:
                response = requests.get(url, params=params, headers=headers) 
                response.raise_for_status()
            except requests.exceptions.HTTPError as e: 
                print("HTTP error", e)
            except requests.exceptions.RequestException as e: 
                print("Request error", e)
            else:
                # retrieve and return the dose rate
                dose_rate = response.json() 
                dose_rate_val = dose_rate['dose rate']['value']
                units = dose_rate['dose rate']['units']

                print(f"Dose rate is {dose_rate_val} {units}")
        - lang: Javascript
          source: |-
            let url = 'https://avrad.amentum.io/parma/ambient_dose?'

            var params = new URLSearchParams({
                altitude : 11, // km 
                latitude : 30, // degrees (N)
                longitude : 30, // degrees (E)
                year : 2019,  
                month : 12,
                day : 1,
                particle : "proton"
            })

            var requestOptions = {
              method: 'GET',
              redirect: 'follow',
              headers: {'API-Key': '<add_your_key>'} 
            };

            fetch(url + params, requestOptions)
              .then(response => response.text())
              .then(result => console.log(result))
              .catch(error => console.log('error', error));
  /parma/differential_intensity:
    get:
      description: |
        The differential intensity of a particle is a directional quantity that describes the number of particles per unit area, per unit solid angle, per unit energy, and per unit time. The API leverages the functionality of PARMA to calculate differential intensity distributions with energies in units of MeV and Intensity in units of /cm2/sr/MeV/s.
      operationId: app.api_parma.endpoints.PARMA.differential_intensity
      parameters:
        - description: Altitude (in km). The minimum is 0 m, the maximum is 47 km (the upper limit of the stratosphere).
          in: query
          name: altitude
          required: false
          schema:
            example: 11
            type: number
        - description: |
            Atmospheric depth from the top of the atmosphere (in units of g/cm2). The minimum is 0.913 g/cm2, the maximum is 1032.66 g/cm2. WARNING: you can specify either altitude OR atmospheric depth, not both.
          in: query
          name: atmospheric_depth
          required: false
          schema:
            example: 0.92
            type: number
        - description: Latitude. -90 (S) to 90 (N).
          in: query
          name: latitude
          required: true
          schema:
            example: 30
            type: number
        - description: Longitude. -180 (W) to 180 (E).
          in: query
          name: longitude
          required: true
          schema:
            example: 30
            type: number
        - description: Year in YYYY.
          in: query
          name: year
          required: true
          schema:
            example: 2019
            type: integer
        - description: Month in MM.
          in: query
          name: month
          required: true
          schema:
            example: 12
            type: integer
        - description: Day in DD.
          in: query
          name: day
          required: true
          schema:
            example: 1
            type: integer
        - description: |
            The particle type as a string. Specifying 'total', only used for the dose calculation, returns the dose for all particle types.
          in: query
          name: particle
          required: true
          schema:
            enum:
              - total
              - e-
              - e+
              - mu+
              - mu-
              - gamma
              - neutron
              - proton
              - alpha
            example: proton
            type: string
        - description: Direction cosine. 1.0 is in the downward direction.
          in: query
          name: angle
          required: true
          schema:
            example: 1
            type: number
      responses:
        "200":
          content:
            application/json:
              schema:
                example:
                  energies:
                    data:
                      - 10.592537251772889
                      - 11.885022274370186
                      - 13.335214321633243
                      - 14.96235656094434
                      - 16.78804018122561
                      - 18.836490894898017
                      - 21.134890398366483
                      - 23.71373705661657
                      - 26.60725059798812
                      - 29.853826189179625
                      - 33.4965439157828
                      - 37.583740428844465
                      - 42.16965034285828
                      - 47.31512589614811
                      - 53.08844442309891
                      - 59.56621435290114
                      - 66.83439175686158
                      - 74.98942093324571
                      - 84.13951416451967
                      - 94.40608762859253
                      - 105.92537251772909
                      - 118.85022274370202
                      - 133.35214321633254
                      - 149.62356560944343
                      - 167.88040181225605
                      - 188.36490894898
                      - 211.34890398366454
                      - 237.1373705661653
                      - 266.0725059798806
                      - 298.5382618917954
                      - 334.9654391578269
                      - 375.83740428844317
                      - 421.69650342858097
                      - 473.1512589614788
                      - 530.8844442309862
                      - 595.662143529008
                      - 668.3439175686115
                      - 749.894209332452
                      - 841.3951416451905
                      - 944.0608762859177
                      - 1059.2537251772821
                      - 1188.5022274370106
                      - 1333.5214321633146
                      - 1496.2356560944222
                      - 1678.804018122547
                      - 1883.6490894897847
                      - 2113.4890398366283
                      - 2371.3737056616337
                      - 2660.725059798784
                      - 2985.38261891793
                      - 3349.6543915782418
                      - 3758.374042884401
                      - 4216.965034285775
                      - 4731.512589614749
                      - 5308.84444230982
                      - 5956.621435290031
                      - 6683.4391756860605
                      - 7498.942093324459
                      - 8413.951416451835
                      - 9440.6087628591
                      - 10592.537251772736
                      - 11885.022274370007
                      - 13335.214321633035
                      - 14962.356560944098
                      - 16788.04018122533
                      - 18836.49089489769
                      - 21134.890398366108
                      - 23713.737056616137
                      - 26607.250597987622
                      - 29853.82618917905
                      - 33496.543915782146
                      - 37583.74042884371
                      - 42169.65034285741
                      - 47315.12589614711
                      - 53088.44442309776
                      - 59566.21435289981
                      - 66834.39175686006
                      - 74989.42093324398
                      - 84139.51416451768
                      - 94406.08762859023
                    units: MeV
                  intensities:
                    data:
                      - 0.000015126557258481497
                      - 0.00001599438328728434
                      - 0.00001689468409778281
                      - 0.00001782700110028125
                      - 0.000018789989894315395
                      - 0.000019781312921179226
                      - 0.00002079773698769471
                      - 0.000021835319990199245
                      - 0.00002288931588809045
                      - 0.000023953698331015904
                      - 0.000025020740419725837
                      - 0.00002608079723261754
                      - 0.00002712202346190026
                      - 0.000028129941429425255
                      - 0.000029086999403906575
                      - 0.000029972245159538348
                      - 0.00003076112412042979
                      - 0.00003142535794905927
                      - 0.000031932955656189876
                      - 0.000032248618858073125
                      - 0.000032334985958519275
                      - 0.000032155208240777106
                      - 0.000031677197295996437
                      - 0.000030879552903400744
                      - 0.000029726220825502388
                      - 0.000028234425803141926
                      - 0.00002650516406182499
                      - 0.000024602269634120444
                      - 0.000022594819983033717
                      - 0.000020552475431477016
                      - 0.00001853662594721251
                      - 0.000016596094572091987
                      - 0.00001476576885147725
                      - 0.000013067285256001253
                      - 0.000011511187862538484
                      - 0.000010100122716208363
                      - 0.00000883240101591408
                      - 0.000007703733932387032
                      - 0.00000670576631351448
                      - 0.000005822881145729626
                      - 0.000005046340372076868
                      - 0.000004369966582442526
                      - 0.000003781202020752834
                      - 0.0000032689518931964352
                      - 0.0000028234311080639376
                      - 0.000002436034648930342
                      - 0.0000020992258398508115
                      - 0.0000018064235849092022
                      - 0.0000015518898432506667
                      - 0.000001331051662285105
                      - 0.0000011394488995132188
                      - 9.726057340258263e-7
                      - 8.265824310558272e-7
                      - 6.998212586927555e-7
                      - 5.894224376580005e-7
                      - 4.93568138996158e-7
                      - 4.116922090268701e-7
                      - 3.460236317178158e-7
                      - 3.037548828699797e-7
                      - 2.9135185653116735e-7
                      - 2.82520391784604e-7
                      - 2.3785220594554244e-7
                      - 1.7791153699257012e-7
                      - 1.2924247345559558e-7
                      - 9.48243126183575e-8
                      - 7.043455232978242e-8
                      - 5.2623996885656347e-8
                      - 3.935459373084662e-8
                      - 2.939334162588793e-8
                      - 2.1909771678801793e-8
                      - 1.6297871509147514e-8
                      - 1.2099955678192665e-8
                      - 8.967477745797399e-9
                      - 6.635335072413951e-9
                      - 4.902621621420823e-9
                      - 3.6176621571186638e-9
                      - 2.6663515657204105e-9
                      - 1.963121398302903e-9
                      - 1.4439864047128638e-9
                      - 1.0612233263106733e-9
                    units: /cm2/s/sr/MeV
                properties:
                  energies:
                    properties:
                      data:
                        items:
                          type: number
                        type: array
                      units:
                        type: string
                    type: object
                  intensities:
                    properties:
                      data:
                        items:
                          type: number
                        type: array
                      units:
                        type: string
                    type: object
                type: object
          description: Successful read of intensity operation
      summary: The energy differential intensity of a particle at a given zenith angle.
      tags:
        - parma
      x-codeSamples:
        - lang: Shell
          source: |
            curl -X GET "https://avrad.amentum.io/parma/differential_intensity?altitude=11&latitude=30&longitude=30&year=2019&month=12&day=1&particle=proton&angle=1.0" -H "API-Key: <your_key>" -H  "accept: application/json"
        - lang: Python
          source: |
            import requests

            params = {
                "altitude" : 11, # km 
                "latitude" : 30, # degrees (N)
                "longitude" : 30, # degrees (E)
                "year" : 2019, # 
                "month" : 12,
                "day" : 1,
                "particle" : "proton",
                "angle" : 1.0
            }
            headers = {"API-Key" : "<add_your_key>"}

            url = "https://avrad.amentum.io/parma/differential_intensity"

            # make the call and handle errors
            try:
                response = requests.get(url, params=params, headers=headers) 
                response.raise_for_status()
            except requests.exceptions.HTTPError as e: 
                print("HTTP error", e)
            except requests.exceptions.RequestException as e: 
                print("Request error", e)
            else:
                # retrieve and return the flux
                json_payload = response.json()

                kes = json_payload["energies"]["data"] # MeV
                flux = json_payload["intensities"]["data"] # /cm2/s/sr/MeV

                print(f"Kinetic energies: {kes} MeV")
                print(f"Intensities: {flux} /cm2/s/sr/MeV")
        - lang: Javascript
          source: |
            let url = 'https://avrad.amentum.io/parma/differential_intensity?'

            var params = new URLSearchParams({
                altitude : 11, // km 
                latitude : 30, // degrees (N)
                longitude : 30, // degrees (E)
                year : 2019,  
                month : 12,
                day : 1,
                particle : 'proton',
                angle : 1.0
            })

            var requestOptions = {
              method: 'GET',
              redirect: 'follow',
              headers: {'API-Key': '<add_your_key>'} 
            };

            fetch(url + params, requestOptions)
              .then(response => response.text())
              .then(result => console.log(result))
              .catch(error => console.log('error', error));
  /parma/effective_dose:
    get:
      description: |
        Effective dose is a radiation protection quantity defined by the International Commission on Radiological Protection (ICRP) and represents the stochastic health risk to the human body at low levels of radiation. It accounts for the different sensitivities of organs to ionising radiation, as well as the different effectiveness of various types of radiation.
        Use this endpoint if you need to estimate radiation exposures of personnel.
      operationId: app.api_parma.endpoints.PARMA.effective_dose
      parameters:
        - description: Altitude (in km). The minimum is 0 m, the maximum is 47 km (the upper limit of the stratosphere).
          in: query
          name: altitude
          required: false
          schema:
            example: 11
            type: number
        - description: |
            Atmospheric depth from the top of the atmosphere (in units of g/cm2). The minimum is 0.913 g/cm2, the maximum is 1032.66 g/cm2. WARNING: you can specify either altitude OR atmospheric depth, not both.
          in: query
          name: atmospheric_depth
          required: false
          schema:
            example: 0.92
            type: number
        - description: Latitude. -90 (S) to 90 (N).
          in: query
          name: latitude
          required: true
          schema:
            example: 30
            type: number
        - description: Longitude. -180 (W) to 180 (E).
          in: query
          name: longitude
          required: true
          schema:
            example: 30
            type: number
        - description: Year in YYYY.
          in: query
          name: year
          required: true
          schema:
            example: 2019
            type: integer
        - description: Month in MM.
          in: query
          name: month
          required: true
          schema:
            example: 12
            type: integer
        - description: Day in DD.
          in: query
          name: day
          required: true
          schema:
            example: 1
            type: integer
        - description: |
            The particle type as a string. Specifying 'total', only used for the dose calculation, returns the dose for all particle types.
          in: query
          name: particle
          required: true
          schema:
            enum:
              - total
              - e-
              - e+
              - mu+
              - mu-
              - gamma
              - neutron
              - proton
              - alpha
            example: proton
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                example:
                  dose rate:
                    units: uSv/hr
                    value: 1.9456004308224644
                properties:
                  dose rate:
                    properties:
                      units:
                        type: string
                      value:
                        type: number
                    type: object
                type: object
          description: Successful dose read operation
      summary: |
        The effective dose rate calculated for a single particle type, or accumulated over all particle types.
      tags:
        - parma
      x-codeSamples:
        - lang: Shell
          source: |
            curl -X GET "https://avrad.amentum.io/parma/effective_dose?altitude=11&latitude=30&longitude=30&year=2019&month=12&day=1&particle=total" -H "API-Key: <your_key>" -H  "accept: application/json" 
        - lang: Python
          source: |
            import requests
            params = {
                "altitude" : 11, #km 
                "latitude" : 30, #degrees (N)
                "longitude" : 30, #degrees (E)
                "year" : 2019,  
                "month" : 12,
                "day" : 1,
                "particle" : "total"
            }
            headers = {"API-Key" : "<add_your_key>"}
            url = "https://avrad.amentum.io/parma/effective_dose"
            try:
                response = requests.get(url, params=params, headers=headers) 
                response.raise_for_status()
            except requests.exceptions.HTTPError as e: 
                print("HTTP error", e)
            except requests.exceptions.RequestException as e: 
                print("Request error", e)
            else:
                # retrieve and return the dose rate
                dose_rate = response.json() 
                dose_rate_val = dose_rate['dose rate']['value']
                units = dose_rate['dose rate']['units']

                print(f"Dose rate is {dose_rate_val} {units}")
        - lang: Javascript
          source: |
            let url = 'https://avrad.amentum.io/parma/effective_dose?'

            var params = new URLSearchParams({
                altitude : 11, // km 
                latitude : 30, // degrees (N)
                longitude : 30, // degrees (E)
                year : 2019,  
                month : 12,
                day : 1,
                particle : "total"
            })

            var requestOptions = {
              method: 'GET',
              redirect: 'follow',
              headers: {'API-Key': '<add_your_key>'} 
            };

            fetch(url + params, requestOptions)
              .then(response => response.text())
              .then(result => console.log(result))
              .catch(error => console.log('error', error));
  /route/ambient_dose:
    get:
      description: |
        The ambient dose equivalent, H*(10), is an operational quantity that simulates the  human body by measuring the dose equivalent at a depth of 10 mm within a tissue  equivalent sphere of 300 mm diameter. It is a measurable quantity that is  used to calibrate area monitors (radiation detectors) for mixed radiation fields.  <br> <br> Use this endpoint if you are comparing model predictions to measurements. <br> <br> This API can run in two modes: <br> <br> Either specify <br> <b>altitude</b>, <b>duration</b><br> for constant altitude calculations; <br> <br> Or specify <br> <b>initial_altitude</b>, <b>cruising_altitudes</b>, <b>climb_times</b>, <b>cruising_times</b>, <b>descent_time</b>, <b>final_altitude</b><br> to calculate dose accounting for a step climb. <br> <br> Note: the airport codes or coordinates (depending on which was specified), and the date in DD/MM/YYYY format, are echoed in the json response as strings.
      operationId: app.api_icaro.endpoints.ICARO.ambient_dose
      parameters:
        - description: The ICAO code or IATA code or latitude,longitude pair (in decimal degrees) of the origin airport.
          in: query
          name: origin
          required: true
          schema:
            example: YSSY
            type: string
        - description: The ICAO code or IATA code or latitude,longitude pair (in decimal degrees) of the destination airport.
          in: query
          name: destination
          required: true
          schema:
            example: 33.94250107,-118.4079971
            type: string
        - description: Altitude (in km). The minimum is 0 m, the maximum is 20 km.
          in: query
          name: altitude
          required: false
          schema:
            example: 10.1
            type: number
        - description: The flight duration in hours. The minimum is 0, the maximum is 20 hrs.
          in: query
          name: duration
          required: false
          schema:
            example: 5
            type: number
        - description: Initial altitude (in km). The minimum is 0 m, the maximum is 20 km.
          in: query
          name: initial_altitude
          required: false
          schema:
            example: 0
            type: number
        - description: Cruising altitudes (in km). The minimum is 0 m, the maximum is 20 km.
          in: query
          name: cruising_altitudes
          required: false
          schema:
            example:
              - 10
              - 15
            items:
              type: number
            type: array
        - description: Climb times for each cruising altitude (hours).
          in: query
          name: climb_times
          required: false
          schema:
            example:
              - 0.1
              - 0.5
            items:
              type: number
            type: array
        - description: Cruising times at each cruising altitude (hours).
          in: query
          name: cruising_times
          required: false
          schema:
            example:
              - 1
              - 2
            items:
              type: number
            type: array
        - description: Descent time from last cruising altitude to final altitude (hours).
          in: query
          name: descent_time
          required: false
          schema:
            example: 0.5
            type: number
        - description: Final altitude (in km).
          in: query
          name: final_altitude
          required: false
          schema:
            example: 0
            type: number
        - description: Year in YYYY.
          in: query
          name: year
          required: true
          schema:
            example: 2019
            type: integer
        - description: Month in MM.
          in: query
          name: month
          required: true
          schema:
            example: 5
            type: integer
        - description: Day in DD.
          in: query
          name: day
          required: true
          schema:
            example: 21
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                example:
                  dose:
                    date: 21/05/2019
                    destination: 33.94250107,-118.4079971
                    origin: YSSY
                    units: uSv
                    value: 10.911498908287665
                properties:
                  dose:
                    properties:
                      date:
                        type: string
                      destination:
                        type: string
                      origin:
                        type: string
                      units:
                        type: string
                      value:
                        type: number
                    type: object
                type: object
          description: Successful dose calculation
      summary: |
        Calculate the ambient equivalent dose along a great circle flight route.
      tags:
        - routedose
      x-codeSamples:
        - lang: Shell
          source: |
            curl -X GET "https://avrad.amentum.io/route/ambient_dose?origin=YSSY&destination=33.94250107,-118.4079971&altitude=10.1&duration=5&year=2019&month=5&day=21" -H "API-Key: <your_key>" -H  "accept: application/json"
        - label: "Python: Constant altitude"
          lang: Python
          source: |
            """
            Constant altitude code sample.

            In this example, we set:
              altitude and duration

            The following parameters are left unset:
              initial_altitude, cruising_altitudes, climb_times,
              cruising_times, descent_time and final_altitude
            """

            import requests

            params = {
              "origin" : "YSSY", # can be ICAO or iATA codes
              "destination" : "33.94250107,-118.4079971",
              "altitude" : 10.1, # km,
              "duration" : 5, # hours
              "year" : 2019,
              "month" : 5,
              "day" : 21
            }
            headers = {"API-Key" : "<add_your_key>"}
            try:
              response = requests.get("https://avrad.amentum.io/route/ambient_dose",
                params=params, headers=headers)
              response_json = response.json()
              response.raise_for_status()
            except requests.exceptions.HTTPError as e:
              print(response_json['error'])
            else:
              dose = response_json['dose']['value']
              print(f"Total Ambient Dose was {dose:.2f} uSv")
        - label: "Python: Step climb"
          lang: Python
          source: |
            """
            Step-climb code sample.

            In this example, we set:
              initial_altitude, cruising_altitudes, climb_times,
              cruising_times, descent_time and final_altitude

            The following parameters are left unset:
              altitude and duration
            """

            import requests

            params = {
              "origin" : "YSSY", # can be ICAO or iATA codes
              "destination" : "33.94250107,-118.4079971",
              "initial_altitude": 0.0,                      # km
              "cruising_altitudes": [12.0, 15.0, 18.0],     # km
              "climb_times": [0.5, 0.25, 0.1],              # hours
              "cruising_times": [1.5, 1.75, 5.0],           # hours
              "descent_time": 0.5,                          # hours
              "final_altitude": 0.0,                        # km
              "year" : 2019,
              "month" : 5,
              "day" : 21
            }
            headers = {"API-Key" : "<add_your_key>"}
            try:
              response = requests.get("https://avrad.amentum.io/route/ambient_dose",
                params=params, headers=headers)
              response_json = response.json()
              response.raise_for_status()
            except requests.exceptions.HTTPError as e:
              print(response_json['error'])
            else:
              dose = response_json['dose']['value']
              print(f"Total Ambient Dose was {dose:.2f} uSv")
        - lang: Javascript
          source: |
            let url = 'https://avrad.amentum.io/route/ambient_dose?'

            var params = new URLSearchParams({
              origin : "YSSY", // can be ICAO or iATA codes
              destination : "33.94250107,-118.4079971",
              altitude : 10.1, // km,
              duration : 5, // hours
              year : 2019,
              month : 5,
              day : 21
            })

            var requestOptions = {
              method: 'GET',
              redirect: 'follow',
              headers: {'API-Key': '<add_your_key>'} 
            };

            fetch(url + params, requestOptions)
              .then(response => response.text())
              .then(result => console.log(result))
              .catch(error => console.log('error', error));
  /route/effective_dose:
    get:
      description: |
        Effective Dose is a radiation protection quantity defined by the International Commission on
         Radiological Protection (ICRP) and represents the stochastic health
         risk to the human body at low levels of radiation.
        It accounts for the different sensitivities of organs to ionising radiation, as well as the different effectiveness of various types of radiation. <br> <br> Use this endpoint if you need to estimate radiation exposures of personnel. <br> <br> This API can run in two modes: <br> <br> Either specify <br> <b>altitude</b>, <b>duration</b><br> for constant altitude calculations; <br> <br> Or specify <br> <b>initial_altitude</b>, <b>cruising_altitudes</b>, <b>climb_times</b>, <b>cruising_times</b>, <b>descent_time</b>, <b>final_altitude</b><br> to calculate dose accounting for a step climb. <br> <br> Note: the airport codes or coordinates (depending on which was specified), and the date in DD/MM/YYYY format, are echoed in the json response as strings.
      operationId: app.api_icaro.endpoints.ICARO.effective_dose
      parameters:
        - description: The ICAO code or IATA code or latitude,longitude pair (in decimal degrees) of the origin airport.
          in: query
          name: origin
          required: true
          schema:
            example: YSSY
            type: string
        - description: The ICAO code or IATA code or latitude,longitude pair (in decimal degrees) of the destination airport.
          in: query
          name: destination
          required: true
          schema:
            example: 33.94250107,-118.4079971
            type: string
        - description: Altitude (in km). The minimum is 0 m, the maximum is 20 km.
          in: query
          name: altitude
          required: false
          schema:
            example: 10.1
            type: number
        - description: The flight duration in hours. The minimum is 0, the maximum is 20 hrs.
          in: query
          name: duration
          required: false
          schema:
            example: 5
            type: number
        - description: Initial altitude (in km). The minimum is 0 m, the maximum is 20 km.
          in: query
          name: initial_altitude
          required: false
          schema:
            example: 0
            type: number
        - description: Cruising altitudes (in km). The minimum is 0 m, the maximum is 20 km.
          in: query
          name: cruising_altitudes
          required: false
          schema:
            example:
              - 10
              - 15
            items:
              type: number
            type: array
        - description: Climb times for each cruising altitude (hours).
          in: query
          name: climb_times
          required: false
          schema:
            example:
              - 0.1
              - 0.5
            items:
              type: number
            type: array
        - description: Cruising times at each cruising altitude (hours).
          in: query
          name: cruising_times
          required: false
          schema:
            example:
              - 1
              - 2
            items:
              type: number
            type: array
        - description: Descent time from last cruising altitude to final altitude (hours).
          in: query
          name: descent_time
          required: false
          schema:
            example: 0.5
            type: number
        - description: Final altitude (in km).
          in: query
          name: final_altitude
          required: false
          schema:
            example: 0
            type: number
        - description: Year in YYYY.
          in: query
          name: year
          required: true
          schema:
            example: 2019
            type: integer
        - description: Month in MM.
          in: query
          name: month
          required: true
          schema:
            example: 5
            type: integer
        - description: Day in DD.
          in: query
          name: day
          required: true
          schema:
            example: 21
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                example:
                  dose:
                    date: 21/05/2019
                    destination: 33.94250107,-118.4079971
                    origin: YSSY
                    units: uSv
                    value: 9.90406659800017
                properties:
                  dose:
                    properties:
                      date:
                        type: string
                      destination:
                        type: string
                      origin:
                        type: string
                      units:
                        type: string
                      value:
                        type: number
                    type: object
                type: object
          description: Successful dose calculation
      summary: |
        Calculate the total effective dose along a great circle flight route.
      tags:
        - routedose
      x-codeSamples:
        - lang: Shell
          source: |
            curl -X GET "https://avrad.amentum.io/route/effective_dose?origin=YSSY&destination=33.94250107,-118.4079971&altitude=10.1&duration=5&year=2019&month=5&day=21" -H "API-Key: <your_key>" -H "accept: application/json"
        - label: "Python: Constant altitude"
          lang: Python
          source: |
            """
            Constant altitude code sample.

            In this example, we set:
              altitude and duration

            The following parameters are left unset:
              initial_altitude, cruising_altitudes, climb_times,
              cruising_times, descent_time and final_altitude
            """

            import requests

            params = {
              "origin" : "YSSY", # can be ICAO or iATA codes
              "destination" : "33.94250107,-118.4079971",
              "altitude" : 10.1, # km,
              "duration" : 5, # hours
              "year" : 2019,
              "month" : 5,
              "day" : 21
            } 
            headers = {"API-Key" : "<add_your_key>"}
            try:
              response = requests.get("https://avrad.amentum.io/route/effective_dose",
                params=params, headers=headers)
              response_json = response.json()
              response.raise_for_status()
            except requests.exceptions.HTTPError as e:
              print(response_json['error'])
            else:
              # Extract the dose
              dose = response_json['dose']['value']
              print(f"Total Effective Dose was {dose:.2f} uSv")
        - label: "Python: Step climb"
          lang: Python
          source: |
            """
            Step-climb code sample.

            In this example, we set:
              initial_altitude, cruising_altitudes, climb_times,
              cruising_times, descent_time and final_altitude

            The following parameters are left unset:
              altitude and duration
            """

            import requests

            params = {
              "origin" : "YSSY", # can be ICAO or iATA codes
              "destination" : "33.94250107,-118.4079971",
              "initial_altitude": 0.0,                      # km
              "cruising_altitudes": [12.0, 15.0, 18.0],     # km
              "climb_times": [0.5, 0.25, 0.1],              # hours
              "cruising_times": [1.5, 1.75, 5.0],           # hours
              "descent_time": 0.5,                          # hours
              "final_altitude": 0.0,                        # km
              "year" : 2019,
              "month" : 5,
              "day" : 21
            }
            headers = {"API-Key" : "<add_your_key>"}
            try:
              response = requests.get("https://avrad.amentum.io/route/effective_dose",
                params=params, headers=headers)
              response_json = response.json()
              response.raise_for_status()
            except requests.exceptions.HTTPError as e:
              print(response_json['error'])
            else:
              # Extract the dose
              dose = response_json['dose']['value']
              print(f"Total Effective Dose was {dose:.2f} uSv")
        - lang: Javascript
          source: |
            let url = 'https://avrad.amentum.io/route/effective_dose?'

            var params = new URLSearchParams({
              origin : "YSSY", // can be ICAO or iATA codes
              destination : "33.94250107,-118.4079971",
              altitude : 10.1, // km,
              duration : 5, // hours
              year : 2019,
              month : 5,
              day : 21
            })

            var requestOptions = {
              method: 'GET',
              redirect: 'follow',
              headers: {'API-Key': '<add_your_key>'} 
            };

            fetch(url + params, requestOptions)
              .then(response => response.text())
              .then(result => console.log(result))
              .catch(error => console.log('error', error));
x-tagGroups:
  - name: Calculate radiation dose along a great circle flight route
    tags:
      - routedose
  - name: Calculate radiation intensity or dose at a point
    tags:
      - cari7
      - parma
