openapi: 3.0.0
servers:
  - url: ""
info:
  contact:
    x-twitter: amentumspace
  description: |
    Space has a hostile radiation environment that increases the risk of cancers in humans and malfunctions in spacecraft electronics. The types of space  radiation of primary concern are:
      <ul>
        <li>
            Galactic Cosmic Rays from outside our solar system generated by 
            supernovae and other phenomena;
        </li>
        <li>
            Solar Energetic Particles produced by the Sun during intense and
            sporadic bursts of activity; and
        </li>
        <li>
            Trapped Radiation: energetic particles confined by Earth's magnetic
            field, usually comprising an inner belt of mostly high energy protons 
            and an outer belt dominated by lower energy electrons and plasma.
        </li>
      </ul> 

    Understanding the space radiation environment for a particular mission profile is becoming increasingly important. Commercial off-the-shelf electronic components  that aren't resilient to space radiation are now prevalent. Longer duration  missions to cislunar space, Mars, and beyond are placing astronauts at greater  risk of radiation exposure. <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: Space Radiation API
  version: 1.1.2
  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://spaceradiation.amentum.space/openapi.json
      version: "3.0"
  x-providerName: amentum.space
  x-serviceName: space_radiation
tags:
  - description: |
      AE9/AP9/SPM is a set of models developed by the US Air Force Research Laboratory that calculates the fluxes of trapped radiation (radiation belt and plasma particles in near-Earth space) for use in space system design,  mission planning, and other climatological applications. <br><br>
      A description of the AE9/AP9/SPM models, including energy ranges for which the respective models are valid, can be found <a href='https://www.vdl.afrl.af.mil/programs/ae9ap9/'>here</a>. <br><br>
      The following endpoints wrap the original Ae9Ap9 code (version 1.50.001) which is available <a href='https://www.vdl.afrl.af.mil/programs/ae9ap9/downloads.php'>here</a>.  <br><br>
      Note: The AE9/AP9/SPM models use the International Geomagnetic Reference Field 12 that is valid for dates between decimal years 2015.0 and 2020.0. If a decimal year greater than 2020.0 is specified as input, the  IGRF values are approximated by those of 31st December 2019. According to the model authors, this approximation is insignificant compared to other uncertainties, and will  be improved with the release of v1.6 of the Ae9Ap9 code (scheduled for 2023).<br><br>
    name: trapped
    x-displayName: AE9/AP9/SPM trapped radiation models
  - description: |
      This endpoint provides access to Amentum's implementation of the  DLR Galactic Cosmic Radiation model.     <br><br> A description of the model can be found in the scientific article  <a href="https://www.sciencedirect.com/science/article/abs/pii/S0273117712005947">"A ready-to-use galactic cosmic ray model"</a>,  Matthiä, Daniel, et al., Advances in Space Research 51.3 (2013): 329-338.  <br><br> It accounts for solar modulation using a single parameter, <i>W</i>,  derived from measurements of carbon flux by the Cosmic Ray Isotope Spectrometer aboard the Advanced Composition Explorer spacecraft.<br><br> A linear relationship between <i>W</i> and terrestrial based neutron monitor count rates (measured at the Oulu station in Finland) has been established:<br> W = -0.093 cr + 638.7 <br> Our implementation uses Oulu station count rates as input,  calculating galactic cosmic ray flux on a particular date. 
    name: gcr
    x-displayName: DLR galactic cosmic radiation model
paths:
  /gcr/flux_dlr:
    get:
      description: |
        for the given energy, atomic number, and date.
      operationId: app.api.endpoints.GCR.calculate_dlr_flux
      parameters:
        - $ref: "#/components/parameters/Year"
        - $ref: "#/components/parameters/Month"
        - $ref: "#/components/parameters/Day"
        - $ref: "#/components/parameters/Z"
        - $ref: "#/components/parameters/Energy"
      responses:
        "200":
          content:
            application/json:
              example:
                flux:
                  units: /m^2/s/sr/(MeV/n)
                  value: 0.006709578488527858
              schema:
                $ref: "#/components/schemas/FluxAtEnergy"
          description: Successful flux calculation
      summary: |
        Calculate particle flux 
      tags:
        - gcr
      x-codeSamples:
        - lang: Shell
          source: |
            curl -X GET "https://spacerad.amentum.io/gcr/flux_dlr?year=2017&month=1&day=1&z=6&energy=100"  -H "API-Key: <your_key>" -H  "accept: application/json"
        - lang: Python
          source: |
            import requests

            params = dict(
              year=2017,
              month=1,
              day=1, 
              z=6,
              energy=100
            )
            headers = {"API-Key" : "<add_your_key>"}
            # Make the API call
            try:
              response = requests.get("https://spacerad.amentum.io/gcr/flux_dlr", 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 flux
              flux = response_json['flux']['value']
              f_unit = response_json['flux']['units']
              print("Flux: ", flux, f_unit)
  /trapped/flux_mean:
    get:
      description: |
        at given coordinates and date-time.
      operationId: app.api.endpoints.TrappedRadiation.calculate_flux_mean
      parameters:
        - $ref: "#/components/parameters/Model"
        - $ref: "#/components/parameters/CoordSystem"
        - $ref: "#/components/parameters/CoordUnits"
        - $ref: "#/components/parameters/Coord1"
        - $ref: "#/components/parameters/Coord2"
        - $ref: "#/components/parameters/Coord3"
        - $ref: "#/components/parameters/Year"
        - $ref: "#/components/parameters/Month"
        - $ref: "#/components/parameters/Day"
        - $ref: "#/components/parameters/Hour"
        - $ref: "#/components/parameters/Minute"
        - $ref: "#/components/parameters/Second"
      responses:
        "200":
          content:
            application/json:
              example:
                energies:
                  data:
                    - 0.04
                    - 0.07
                    - 0.1
                    - 0.25
                    - 0.5
                    - 0.75
                    - 1
                    - 1.5
                    - 2
                    - 2.5
                    - 3
                    - 3.5
                    - 4
                    - 4.5
                    - 5
                    - 5.5
                    - 6
                    - 6.5
                    - 7
                    - 8.5
                    - 10
                  units: MeV
                flux:
                  data:
                    - 854635898.3161561
                    - 564685905.5669771
                    - 178490117.91626602
                    - 47643571.94054352
                    - 12254101.813260391
                    - 4549350.837767644
                    - 1803653.1511005901
                    - 654692.4848865604
                    - 207898.83220077943
                    - 64091.642036893325
                    - 21119.72803543081
                    - 7526.08326415376
                    - 2847.94993909225
                    - 1117.8011168229402
                    - 490.68560475708034
                    - 269.114292404757
                    - 177.84563745629936
                    - 128.22793816827138
                    - 78.49896611035479
                    - 43.74101815451732
                    - 30.335272788461896
                  units: /cm^2/s/MeV
              schema:
                $ref: "#/components/schemas/Flux"
          description: Successful flux calculation
      summary: |
        Calculate mean particle flux
      tags:
        - trapped
      x-codeSamples:
        - lang: Shell
          source: |
            curl -X GET "https://spacerad.amentum.io/trapped/flux_mean?model=AE9&coord_sys=GEI&coord_units=KM&coord1=3216.6&coord2=35426&coord3=603.4&year=2017&month=1&day=1&hour=0&minute=0&second=0"  -H "API-Key: <your_key>" -H  "accept: application/json"
        - lang: Python
          source: |
            import requests

            params = dict(
              model="AE9", # proton flux
              coord_sys="GEI", # Geocentric equatorial inertial
              coord_units="KM", # kilometers
              coord1=3216.6, # in KM
              coord2=35426,
              coord3=603.4,
              year=2017,
              month=1,
              day=1, 
              hour=0,
              minute=0,
              second=0,
            )
            headers = {"API-Key" : "<add_your_key>"}
            # Make the API call
            try:
              response = requests.get("https://spacerad.amentum.io/trapped/flux_mean", 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 flux
              energies = response_json['energies']['data']
              e_unit = response_json['energies']['units']
              flux = response_json['flux']['data']
              f_unit = response_json['flux']['units']
              print("Energies: ", energies, e_unit)
              print("Mean Fluxes: ", flux, f_unit)
  /trapped/flux_percentile:
    get:
      description: |
        at given coordinates and date-time.
      operationId: app.api.endpoints.TrappedRadiation.calculate_flux_percentile
      parameters:
        - $ref: "#/components/parameters/Model"
        - $ref: "#/components/parameters/CoordSystem"
        - $ref: "#/components/parameters/CoordUnits"
        - $ref: "#/components/parameters/Coord1"
        - $ref: "#/components/parameters/Coord2"
        - $ref: "#/components/parameters/Coord3"
        - $ref: "#/components/parameters/Year"
        - $ref: "#/components/parameters/Month"
        - $ref: "#/components/parameters/Day"
        - $ref: "#/components/parameters/Hour"
        - $ref: "#/components/parameters/Minute"
        - $ref: "#/components/parameters/Second"
        - $ref: "#/components/parameters/Percentile"
      responses:
        "200":
          content:
            application/json:
              example:
                energies:
                  data:
                    - 0.04
                    - 0.07
                    - 0.1
                    - 0.25
                    - 0.5
                    - 0.75
                    - 1
                    - 1.5
                    - 2
                    - 2.5
                    - 3
                    - 3.5
                    - 4
                    - 4.5
                    - 5
                    - 5.5
                    - 6
                    - 6.5
                    - 7
                    - 8.5
                    - 10
                  units: MeV
                flux:
                  data:
                    - 448667784.4812672
                    - 322139086.68134594
                    - 116785893.33177781
                    - 32665389.706181422
                    - 7991547.299112285
                    - 2586068.6893010717
                    - 839339.9184292991
                    - 251004.07802610364
                    - 69547.20063526293
                    - 19974.510921688125
                    - 6379.793949894077
                    - 2089.794228005704
                    - 779.5936616445822
                    - 313.1551441702104
                    - 141.5097428322324
                    - 71.78622535090953
                    - 40.65088904584258
                    - 25.06786549513947
                    - 12.794710202598523
                    - 5.620209093649994
                    - 3.319852121012902
                  units: /cm^2/s/MeV
              schema:
                $ref: "#/components/schemas/Flux"
          description: Successful flux calculation
      summary: |
        Calculate percentile particle flux
      tags:
        - trapped
      x-codeSamples:
        - lang: Shell
          source: |
            curl -X GET "https://spacerad.amentum.io/trapped/flux_percentile?model=AE9&coord_sys=GEI&coord_units=KM&coord1=3216.6&coord2=35426&coord3=603.4&year=2017&month=1&day=1&hour=0&minute=0&second=0&percentile=50"  -H "API-Key: <your_key>" -H  "accept: application/json"
        - lang: Python
          source: |+
            import requests

            params = dict(
              model="AE9", # proton flux
              coord_sys="GEI", # Geocentric equatorial inertial
              coord_units="KM", # kilometers
              coord1=3216.6, # in KM
              coord2=35426,
              coord3=603.4,
              year=2017,
              month=1,
              day=1, 
              hour=0,
              minute=0,
              second=0,
              percentile=50 # median flux
            )

            headers = {"API-Key" : "<add_your_key>"}

            # Make the API call
            try:
              response = requests.get("https://spacerad.amentum.io/trapped/flux_percentile", 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 flux
              energies = response_json['energies']['data']
              e_unit = response_json['energies']['units']
              flux = response_json['flux']['data']
              f_unit = response_json['flux']['units']
              print("Energies: ", energies, e_unit)
              print("Median Fluxes: ", flux, f_unit)
              
components:
  parameters:
    Coord1:
      description: |
        <br>First coordinate value to specify position. <br><br> Ordering for GEI, GEO coords:X, Y, Z<br> Ordering for GDZ coords: Alt, Lat, Long<br>  Valid ranges for latitude: -90, 90<br>  Valid ranges for longitude: 0, 360<br> 
      in: query
      name: coord1
      required: true
      schema:
        example: 3216.6
        type: number
    Coord2:
      description: <br>Second coordinate value.
      in: query
      name: coord2
      required: true
      schema:
        example: 35426
        type: number
    Coord3:
      description: <br>Third coordinate value.
      in: query
      name: coord3
      required: true
      schema:
        example: 603.4
        type: number
    CoordSystem:
      description: |
        <br>Coordinate system to use:  <br><br> - Geodetic/WGS84 (GDZ) <br> - Geocentric Cartesian (GEO) <br> - Geocentric Earth Inertial (GEI) <br> See "Bhavnani, K. H., & Vancour, R. P. (1991).  Coordinate systems for space and geophysical applications"  for coord system definitions.
      in: query
      name: coord_sys
      required: true
      schema:
        enum:
          - GDZ
          - GEO
          - GEI
        example: GEI
        type: string
    CoordUnits:
      description: |
        <br>Coordinate units to use: km (KM) or Earth Radii (RE)
      in: query
      name: coord_units
      required: true
      schema:
        enum:
          - KM
          - RE
        example: KM
        type: string
    Date:
      description: <br>Decimal year (eg 1997.65)
      in: query
      name: date
      required: true
      schema:
        type: number
    Day:
      description: <br>
      in: query
      name: day
      required: true
      schema:
        example: 1
        type: integer
    Energy:
      description: |
        <br>Particle energy in MeV/n<br> Valid range: [0, 10<sup>6</sup>] MeV/n<br> 
      in: query
      name: energy
      required: true
      schema:
        example: 100
        type: number
    Hour:
      description: <br>
      in: query
      name: hour
      required: true
      schema:
        example: "0"
        type: integer
    Minute:
      description: <br>
      in: query
      name: minute
      required: true
      schema:
        example: "0"
        type: integer
    Model:
      description: |
        <br>Which model to use: <br><br> - Energetic electrons (AE9) <br> - Energetic protons (AP9)  <br> - Space plasma model for electrons (SPME) <br> - for hydrogen (SPMH) <br> - for helium (SPMHE) <br> - for oxygen (SPMO) 
      in: query
      name: model
      required: true
      schema:
        enum:
          - AE9
          - AP9
          - SPME
          - SPMH
          - SPMHE
          - SPMO
        example: AE9
        type: string
    Month:
      description: <br>
      in: query
      name: month
      required: true
      schema:
        example: 1
        type: integer
    Percentile:
      description: |
        <br>Integer percentile at which to calc flux (50 is the median value).
      in: query
      name: percentile
      required: true
      schema:
        example: 50
        type: integer
    Second:
      description: <br>
      in: query
      name: second
      required: true
      schema:
        example: "0"
        type: integer
    Year:
      description: <br>
      in: query
      name: year
      required: true
      schema:
        example: 2017
        type: integer
    Z:
      description: <br>Particle atomic number
      in: query
      name: z
      required: true
      schema:
        example: 6
        type: number
  schemas:
    Flux:
      properties:
        energies:
          description: |
            Particle energies at which omnidirectional flux values are calculated, and their units.
          properties:
            data:
              items:
                type: number
              type: array
            units:
              type: string
          type: object
        flux:
          description: |
            Corresponding omnidirectional flux values, and their units.
          properties:
            data:
              items:
                type: number
              type: array
            units:
              type: string
          type: object
      type: object
    FluxAtEnergy:
      properties:
        flux:
          description: |
            Particle flux value and units.
          properties:
            units:
              type: string
            value:
              type: number
          type: object
      type: object
x-tagGroups:
  - name: Trapped Radiation
    tags:
      - trapped
  - name: Galactic Cosmic Radiation
    tags:
      - gcr
