Base Operations Saved Location Charts API

openapi: 3.0.0
info:
  title: Customer API - Base Operations Analytics Saved Location 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 Charts
paths:
  /v1/public/charts/{savedLocationId}/monthly-trend:
    get:
      description: 'This endpoint takes a `savedLocationId` and calculates the number with threats per month within the granularity 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: PublicSavedLocationChartsController_getMonthlyTimeSeries_v1
      parameters:
      - name: savedLocationId
        required: true
        in: path
        schema:
          type: number
      - 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: granularity
        required: true
        in: query
        schema:
          default: city
          type: string
          enum:
          - city
      - 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: 'Saved location not found


            Location not found | Boundary not found | Saved Location not found'
        '422':
          description: Location based information is not available for this saved location | District level data is not available for this location
        '432':
          description: Not enough data available
        '500':
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Saved Location Monthly Time Series Analysis at City or District Level
      tags:
      - Saved Location Charts
  /v1/public/charts/{savedLocationId}/rolling-average:
    get:
      description: 'This endpoint takes a `savedLocationId` and calculates the 30-day rolling average within the granularity 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: PublicSavedLocationChartsController_getRollingAverageTimeSeries_v1
      parameters:
      - name: savedLocationId
        required: true
        in: path
        schema:
          type: number
      - 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: granularity
        required: true
        in: query
        schema:
          default: city
          type: string
          enum:
          - city
      - 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: 'Saved location not found


            Location not found | Boundary not found | Saved Location not found'
        '422':
          description: Location based information is not available for this saved location | District level data is not available for this location
        '432':
          description: Not enough data available
        '500':
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Saved Location 30-day Rolling Average at City or District Level
      tags:
      - Saved Location Charts
  /v1/public/charts/{savedLocationId}/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 granularity provided.<br><br>      **Example:** If you specify a precision `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: PublicSavedLocationChartsController_getMonthlyHistorical_v1
      parameters:
      - name: savedLocationId
        required: true
        in: path
        schema:
          type: number
      - 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: granularity
        required: true
        in: query
        schema:
          default: city
          type: string
          enum:
          - city
      - 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: 'Saved location not found


            Location not found | Boundary not found | Saved Location not found'
        '422':
          description: Location based information is not available for this saved location | District level data is not available for this location
        '432':
          description: Not enough data available
        '500':
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Saved Location Historical Monthly Trend Analysis at City or District Level
      tags:
      - Saved Location Charts
  /v1/public/charts/{savedLocationId}/historical-analysis/day-of-week:
    get:
      operationId: PublicSavedLocationChartsController_getAverageDayOfWeek_v1
      parameters:
      - name: savedLocationId
        required: true
        in: path
        schema:
          type: number
      - 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: granularity
        required: true
        in: query
        schema:
          default: city
          type: string
          enum:
          - city
      - 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/HistoricalMonthlyChartDto'
                - properties:
                    chartData:
                      type: array
                      items:
                        $ref: '#/components/schemas/HistoricalDayOfWeekData'
            text/csv:
              schema:
                type: string
                example: 'day,threatCount,average,fromDate,toDate

                  1,621,12.94,2023-01-03,2023-01-09'
          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: []
      tags:
      - Saved Location Charts
  /v1/public/charts/{savedLocationId}/historical-analysis/time-of-day:
    get:
      operationId: PublicSavedLocationChartsController_getAverageTimeOfDay_v1
      parameters:
      - name: savedLocationId
        required: true
        in: path
        schema:
          type: number
      - 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: granularity
        required: true
        in: query
        schema:
          default: city
          type: string
          enum:
          - city
      - 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/HistoricalMonthlyChartDto'
                - properties:
                    chartData:
                      type: array
                      items:
                        $ref: '#/components/schemas/HistoricalTimeOfDaysData'
            text/csv:
              schema:
                type: string
                example: 'timeOfDay,threatCount,average,fromDate,toDate

                  1,621,12.94,2022-01-02,2022-01-02 23:59:59'
          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: []
      tags:
      - Saved Location Charts
  /v1/public/charts/{savedLocationId}/severity-score:
    get:
      description: 'This endpoint takes a `savedLocationId` and calculates the relative severity of the district that contains your saved location compared to other districts in the city. This is computed for each month to help you analyze the trend over time.<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: PublicSavedLocationChartsController_getSeverityScoreTrend_v1
      parameters:
      - name: savedLocationId
        required: true
        in: path
        schema:
          type: number
      - 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/SeverityScoreData'
            text/csv:
              schema:
                type: string
                example: 'date,severity,average

                  2023-01-01,4,4.5'
          description: ''
        '401':
          description: Unauthorized. Your API Key may be invalid or expired.
        '404':
          description: 'Saved location not found


            Location not found | Boundary not found | Saved Location not found'
        '422':
          description: Severity score trend analysis is not available for this location
        '432':
          description: Not enough data available
        '500':
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Saved Location Severity Score Trend Analysis at District Level
      tags:
      - Saved Location Charts
  /v1/public/charts/{savedLocationId}/threat-quintiles:
    get:
      description: 'This endpoint takes a `savedLocationId` and calculates the severity quintile (1-5) of the district that contains your saved location relative to other districts in the city for each threat category.<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 be acquired by getting all savedLocations from the endpoint `GET /v1/public/saved-locations`.*'
      operationId: PublicSavedLocationChartsController_getThreatQuintiles_v1
      parameters:
      - name: savedLocationId
        required: true
        in: path
        schema:
          type: number
      - 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/ThreatQuintilesDownloadData'
            text/csv:
              schema:
                type: string
                example: 'category,categoryId,severity,count

                  Theft,1,5,16'
          description: ''
        '401':
          description: Unauthorized. Your API Key may be invalid or expired.
        '404':
          description: 'Saved location not found


            Location not found | Boundary not found | Saved Location not found'
        '422':
          description: Threat Quintiles chart is not available for this location
        '432':
          description: Not enough data available
        '500':
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Saved Location Threat Quintile Analysis at District Level
      tags:
      - Saved Location Charts
  /v1/public/charts/{savedLocationId}/threat-categories-trend:
    get:
      description: Retrieves a trend of threat categories count within a specific date range for a specific location.
      operationId: PublicSavedLocationChartsController_getThreatCategoryTrend_v1
      parameters:
      - name: savedLocationId
        required: true
        in: path
        schema:
          type: number
      - 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: granularity
        required: true
        in: query
        schema:
          default: city
          type: string
          enum:
          - city
      - 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 Charts
  /v1/public/charts/{savedLocationId}/source-categories-trend:
    get:
      description: Retrieves a trend of source categories count within a specific date range for a specific location.
      operationId: PublicSavedLocationChartsController_getSourceCategoryTrend_v1
      parameters:
      - name: savedLocationId
        required: true
        in: path
        schema:
          type: number
      - 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: granularity
        required: true
        in: query
        schema:
          default: city
          type: string
          enum:
          - city
      - 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 Charts
  /v1/public/charts/{savedLocationId}/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: PublicSavedLocationChartsController_getEventBreakdown_v1
      parameters:
      - name: savedLocationId
        required: true
        in: path
        schema:
          type: number
      - 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: granularity
        required: true
        in: query
        schema:
          default: city
          type: string
          enum:
          - city
      - name: types
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - crime
            - unrest
            - customer
            - uas_sighting
      - name: sourceIds

# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/base-operations/refs/heads/main/openapi/base-operations-saved-location-charts-api-openapi.yml