Base Operations Saved Location Radius Charts API

openapi: 3.0.0
info:
  title: Customer API - Base Operations Analytics Saved Location Radius Charts API
  description: 'Welcome to the Base Operations Customer API! This API allows you to interact with our data and perform detailed analysis. In this documentation, we''ll explain how to use the API, including the available endpoints and the expected request bodies or query parameters.


    ### Authentication


    To use this API, you''ll need to authenticate using an API key. Please reach out to Base Operations to have an API key provisioned for your user. Once you have your API key, you can use it to authorize the Swagger docs.


    To authenticate on the Swagger docs, follow these steps:


    1.  Click on the "Authorize" button on the top right corner of the Swagger docs.

    2.  In the "Value" field, enter your API key.

    3.  Click "Authorize" to authenticate.


    ### Helpful Hints


    When using the API, you may see the following query parameters:


    - `savedLocationId`: This is an internal identifier for a saved location. You can acquire this identifier by using the `GET /v1/public/saved-locations` endpoint.


    - `categoryId`: This is an internal identifier for a threat category. You can acquire this identifier by using the `GET /v1/public/threat-categories` endpoint.<br><br>


    That''s it! You''re now authenticated and can start using the API. If you have any questions or issues, please contact Base Operations support.

    '
  version: '1.0'
  contact: {}
servers:
- url: https://api.baseoperationsenterprise.com/
tags:
- name: Saved Location Radius Charts
paths:
  /v1/public/charts/{savedLocationId}/radius/monthly-trend:
    get:
      description: 'This endpoint takes a `savedLocationId` and calculates the number with threats per month within the radius provided.<br><br><br>      - The `fromDate` & `toDate` are required [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) query parameters that will restrict or alter the results of this analysis.<br><br>      - The query parameters `type`, `categoryIds`, `months` and `daytimes` are optional but will help you further refine your analysis.<br><br><br>      HINT: The `savedLocationId` can we acquired by getting all savedLocations from the endpoint `GET /v1/public/saved-locations`.'
      operationId: PublicSavedLocationRadiusChartsController_getRadiusMonthlyTimeSeries_v1
      parameters:
      - name: savedLocationId
        required: true
        in: path
        schema:
          type: number
      - name: radius
        required: true
        in: query
        schema:
          default: 0.5
          type: number
      - name: units
        required: true
        in: query
        description: 'NB: miles, kilometers and meters will be deprecated soon.'
        schema:
          default: mi
          type: string
          enum:
          - mi
          - km
          - m
          - miles
          - kilometers
          - meters
      - name: fromDate
        required: true
        in: query
        schema:
          format: date-time
          type: string
      - name: toDate
        required: true
        in: query
        schema:
          format: date-time
          type: string
      - name: types
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - crime
            - unrest
            - customer
            - uas_sighting
      - name: sourceIds
        required: false
        in: query
        schema:
          type: array
          items:
            type: number
      - name: categoryIds
        required: false
        in: query
        schema:
          type: array
          items:
            type: number
      - name: months
        required: false
        in: query
        schema:
          type: array
          items:
            type: number
      - name: daytimes
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - morning
            - midmorning
            - afternoon
            - evening
            - night
      - name: isGTM
        required: false
        in: query
        schema:
          default: true
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ChartDto'
                - properties:
                    chartData:
                      type: array
                      items:
                        $ref: '#/components/schemas/TimeSeriesMonthlyChartData'
            text/csv:
              schema:
                type: string
                example: 'date,count,average

                  2023-01-01,50,25'
          description: ''
        '401':
          description: Unauthorized. Your API Key may be invalid or expired.
        '404':
          description: Location not found | Boundary not found | Saved Location not found
        '432':
          description: Not enough data available
        '500':
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Saved Location Monthly Time Series Anaylsis within Radius
      tags:
      - Saved Location Radius Charts
  /v1/public/charts/{savedLocationId}/radius/rolling-average:
    get:
      description: 'This endpoint takes a `savedLocationId` and calculates the 30-day rolling average within the radius provided.<br><br><br>      - The `fromDate` & `toDate` are required [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) query parameters that will restrict or alter the results of this analysis.<br><br>      - The query parameters `type`, `categoryIds`, `months` and `daytimes` are optional but will help you further refine your analysis.<br><br><br>      HINT: The `savedLocationId` can we acquired by getting all savedLocations from the endpoint `GET /v1/public/saved-locations`.'
      operationId: PublicSavedLocationRadiusChartsController_getRadiusRollingAverageTimeSeries_v1
      parameters:
      - name: savedLocationId
        required: true
        in: path
        schema:
          type: number
      - name: radius
        required: true
        in: query
        schema:
          default: 0.5
          type: number
      - name: units
        required: true
        in: query
        description: 'NB: miles, kilometers and meters will be deprecated soon.'
        schema:
          default: mi
          type: string
          enum:
          - mi
          - km
          - m
          - miles
          - kilometers
          - meters
      - name: fromDate
        required: true
        in: query
        schema:
          format: date-time
          type: string
      - name: toDate
        required: true
        in: query
        schema:
          format: date-time
          type: string
      - name: types
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - crime
            - unrest
            - customer
            - uas_sighting
      - name: sourceIds
        required: false
        in: query
        schema:
          type: array
          items:
            type: number
      - name: categoryIds
        required: false
        in: query
        schema:
          type: array
          items:
            type: number
      - name: months
        required: false
        in: query
        schema:
          type: array
          items:
            type: number
      - name: daytimes
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - morning
            - midmorning
            - afternoon
            - evening
            - night
      - name: isGTM
        required: false
        in: query
        schema:
          default: true
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ChartDto'
                - properties:
                    chartData:
                      type: array
                      items:
                        $ref: '#/components/schemas/TimeSeriesRollingChartData'
            text/csv:
              schema:
                type: string
                example: 'date,rollingAverage,average

                  2023-01-01,77.1,77.7'
          description: ''
        '401':
          description: Unauthorized. Your API Key may be invalid or expired.
        '404':
          description: Location not found | Boundary not found | Saved Location not found
        '432':
          description: Not enough data available
        '500':
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Saved Location 30-day Rolling Average within Radius
      tags:
      - Saved Location Radius Charts
  /v1/public/charts/{savedLocationId}/radius/historical-monthly-trend:
    get:
      description: 'This endpoint takes a `savedLocationId` and calculates the monthly average compared to past years based on your chosen precision within the radius provided.<br><br>      **Example:** If you specify a precicion `3_years`, you will see the average of all Januaries within the past 3 years, then Februaries, and so on for every month.<br><br><br>      - The `fromDate` & `toDate` are required [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) query parameters that will restrict or alter the results of this analysis.<br><br>      - The query parameters `type`, `categoryIds`, `months` and `daytimes` are optional but will help you further refine your analysis.<br><br><br>      *HINT: The `savedLocationId` can we acquired by getting all savedLocations from the endpoint `GET /v1/public/saved-locations`.*'
      operationId: PublicSavedLocationRadiusChartsController_getRadiusMonthlyHistorical_v1
      parameters:
      - name: savedLocationId
        required: true
        in: path
        schema:
          type: number
      - name: radius
        required: true
        in: query
        schema:
          default: 0.5
          type: number
      - name: units
        required: true
        in: query
        description: 'NB: miles, kilometers and meters will be deprecated soon.'
        schema:
          default: mi
          type: string
          enum:
          - mi
          - km
          - m
          - miles
          - kilometers
          - meters
      - name: fromDate
        required: true
        in: query
        schema:
          format: date-time
          type: string
      - name: toDate
        required: true
        in: query
        schema:
          format: date-time
          type: string
      - name: types
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - crime
            - unrest
            - customer
            - uas_sighting
      - name: sourceIds
        required: false
        in: query
        schema:
          type: array
          items:
            type: number
      - name: categoryIds
        required: false
        in: query
        schema:
          type: array
          items:
            type: number
      - name: months
        required: false
        in: query
        schema:
          type: array
          items:
            type: number
      - name: daytimes
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - morning
            - midmorning
            - afternoon
            - evening
            - night
      - name: isGTM
        required: false
        in: query
        schema:
          default: true
          type: boolean
      - name: precision
        required: true
        in: query
        schema:
          default: 3_years
          type: string
          enum:
          - 3_years
          - 4_years
          - 5_years
          - full_range
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/HistoricalMonthlyChartDto'
                - properties:
                    chartData:
                      type: array
                      items:
                        $ref: '#/components/schemas/HistoricalMonthlyData'
            text/csv:
              schema:
                type: string
                example: 'month,count,average,fromDate,toDate

                  January,50,25,2023-01-01,2023-06-31'
          description: ''
        '401':
          description: Unauthorized. Your API Key may be invalid or expired.
        '404':
          description: Location not found | Boundary not found | Saved Location not found
        '432':
          description: Not enough data available
        '500':
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Saved Location Historical Monthly Trend Analysis within Radius
      tags:
      - Saved Location Radius Charts
  /v1/public/charts/{savedLocationId}/radius/event-breakdown:
    get:
      description: This endpoint calculates the relationship between parent categories, sub categories, and the time of day that they occur. The data will be returned as an array of nodes and links.
      operationId: PublicSavedLocationRadiusChartsController_getEventBreakdown_v1
      parameters:
      - name: savedLocationId
        required: true
        in: path
        schema:
          type: number
      - name: radius
        required: true
        in: query
        schema:
          default: 0.5
          type: number
      - name: units
        required: true
        in: query
        description: 'NB: miles, kilometers and meters will be deprecated soon.'
        schema:
          default: mi
          type: string
          enum:
          - mi
          - km
          - m
          - miles
          - kilometers
          - meters
      - name: fromDate
        required: true
        in: query
        schema:
          format: date-time
          type: string
      - name: toDate
        required: true
        in: query
        schema:
          format: date-time
          type: string
      - name: types
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - crime
            - unrest
            - customer
            - uas_sighting
      - name: sourceIds
        required: false
        in: query
        schema:
          type: array
          items:
            type: number
      - name: categoryIds
        required: false
        in: query
        schema:
          type: array
          items:
            type: number
      - name: months
        required: false
        in: query
        schema:
          type: array
          items:
            type: number
      - name: daytimes
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - morning
            - midmorning
            - afternoon
            - evening
            - night
      - name: isGTM
        required: false
        in: query
        schema:
          default: true
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ChartDto'
                - properties:
                    chartData:
                      type: array
                      items:
                        $ref: '#/components/schemas/SankeyData'
            text/csv:
              schema:
                type: string
                example: 'source,target,value

                  Theft,morning,16'
          description: ''
        '401':
          description: Unauthorized. Your API Key may be invalid or expired.
        '404':
          description: Location not found | Boundary not found | Saved Location not found
        '432':
          description: Not enough data available
        '500':
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Get Radius Event Breakdown
      tags:
      - Saved Location Radius Charts
  /v1/public/charts/{savedLocationId}/radius/threat-categories-trend:
    get:
      description: Retrieves a trend of threat categories count within a specific date range into a defined radius area.
      operationId: PublicSavedLocationRadiusChartsController_getThreatCategoryTrend_v1
      parameters:
      - name: savedLocationId
        required: true
        in: path
        schema:
          type: number
      - name: radius
        required: true
        in: query
        schema:
          default: 0.5
          type: number
      - name: units
        required: true
        in: query
        description: 'NB: miles, kilometers and meters will be deprecated soon.'
        schema:
          default: mi
          type: string
          enum:
          - mi
          - km
          - m
          - miles
          - kilometers
          - meters
      - name: fromDate
        required: true
        in: query
        schema:
          format: date-time
          type: string
      - name: toDate
        required: true
        in: query
        schema:
          format: date-time
          type: string
      - name: types
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - crime
            - unrest
            - customer
            - uas_sighting
      - name: sourceIds
        required: false
        in: query
        schema:
          type: array
          items:
            type: number
      - name: categoryIds
        required: false
        in: query
        schema:
          type: array
          items:
            type: number
      - name: months
        required: false
        in: query
        schema:
          type: array
          items:
            type: number
      - name: daytimes
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - morning
            - midmorning
            - afternoon
            - evening
            - night
      - name: isGTM
        required: false
        in: query
        schema:
          default: true
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ChartDto'
                - properties:
                    chartData:
                      type: array
                      items:
                        $ref: '#/components/schemas/CategoryTrendData'
            text/csv:
              schema:
                type: string
                example: 'date,categoryId,isParent,count

                  2023-01-01,5,true,100'
          description: ''
        '401':
          description: Unauthorized. Your API Key may be invalid or expired.
        '404':
          description: Location not found | Boundary not found | Saved Location not found
        '432':
          description: Not enough data available
        '500':
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Get Threat Category Trend Chart
      tags:
      - Saved Location Radius Charts
  /v1/public/charts/{savedLocationId}/radius/source-categories-trend:
    get:
      description: Retrieves a trend of source categories count within a specific date range into a defined radius area.
      operationId: PublicSavedLocationRadiusChartsController_getSourceCategoryTrend_v1
      parameters:
      - name: savedLocationId
        required: true
        in: path
        schema:
          type: number
      - name: radius
        required: true
        in: query
        schema:
          default: 0.5
          type: number
      - name: units
        required: true
        in: query
        description: 'NB: miles, kilometers and meters will be deprecated soon.'
        schema:
          default: mi
          type: string
          enum:
          - mi
          - km
          - m
          - miles
          - kilometers
          - meters
      - name: fromDate
        required: true
        in: query
        schema:
          format: date-time
          type: string
      - name: toDate
        required: true
        in: query
        schema:
          format: date-time
          type: string
      - name: types
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - crime
            - unrest
            - customer
            - uas_sighting
      - name: sourceIds
        required: false
        in: query
        schema:
          type: array
          items:
            type: number
      - name: categoryIds
        required: false
        in: query
        schema:
          type: array
          items:
            type: number
      - name: months
        required: false
        in: query
        schema:
          type: array
          items:
            type: number
      - name: daytimes
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - morning
            - midmorning
            - afternoon
            - evening
            - night
      - name: isGTM
        required: false
        in: query
        schema:
          default: true
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ChartDto'
                - properties:
                    chartData:
                      type: array
                      items:
                        $ref: '#/components/schemas/CategoryTrendData'
            text/csv:
              schema:
                type: string
                example: 'date,sourceId,isParent,count

                  2023-01-01,5,true,100'
          description: ''
        '401':
          description: Unauthorized. Your API Key may be invalid or expired.
        '404':
          description: Location not found | Boundary not found | Saved Location not found
        '432':
          description: Not enough data available
        '500':
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Get Source Category Trend Chart
      tags:
      - Saved Location Radius Charts
components:
  schemas:
    TimeSeriesMonthlyChartData:
      type: object
      properties:
        date:
          type: string
        count:
          type: number
        average:
          type: number
      required:
      - date
      - count
      - average
    HistoricalMonthlyChartDto:
      type: object
      properties:
        chartData:
          type: object
        metadata:
          type: object
        fromDate:
          type: string
        toDate:
          type: string
      required:
      - chartData
    SankeyLink:
      type: object
      properties:
        source:
          type: string
        target:
          type: string
        value:
          type: number
      required:
      - source
      - target
      - value
    CategoryTrendData:
      type: object
      properties:
        date:
          type: string
        threatType:
          type: string
          enum:
          - crime
          - unrest
          - customer
          - uas_sighting
        categoryId:
          type: number
        category:
          type: string
        isParent:
          type: boolean
        parentId:
          type: number
          nullable: true
        count:
          type: number
      required:
      - date
      - threatType
      - categoryId
      - category
      - isParent
      - parentId
      - count
    HistoricalMonthlyData:
      type: object
      properties:
        monthNumber:
          type: number
        month:
          type: string
        average:
          type: number
        threatType:
          type: string
      required:
      - monthNumber
      - month
      - average
    TimeSeriesRollingChartData:
      type: object
      properties:
        date:
          type: string
        rollingAverage:
          type: number
      required:
      - date
      - rollingAverage
    SankeyData:
      type: object
      properties:
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/SankeyNode'
        links:
          type: array
          items:
            $ref: '#/components/schemas/SankeyLink'
      required:
      - nodes
      - links
    ChartDto:
      type: object
      properties:
        chartData:
          type: object
        metadata:
          type: object
      required:
      - chartData
    SankeyNode:
      type: object
      properties:
        id:
          oneOf:
          - type: number
          - type: string
        name:
          type: string
        type:
          type: string
        value:
          type: number
      required:
      - id
      - name
      - type
      - value
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-KEY