Base Operations Saved Locations API

openapi: 3.0.0
info:
  title: Customer API - Base Operations Analytics Saved Locations 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 Locations
paths:
  /v1/public/saved-locations:
    post:
      description: 'This endpoint allows you to create a new saved location. Creating a saved location here will also be visible in your dashboard.<br><br>      While only `name`, `latitude`, and `longitude` are required, other parameters will help you organize and analyze your saved locations.<br><br><br>      *HINT: The `id` returned from this endpoint will be used as `savedLocationId` in some analysis endpoints*'
      operationId: PublicSavedLocationsController_create_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLocationDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSavedLocation'
      security:
      - ApiKey: []
      summary: Create Saved Location
      tags:
      - Saved Locations
    get:
      description: 'This endpoint allows you to get all saved locations.<br><br>      You can use the parameters `page`, and `take` to control the pagination, however, there is maximum page size of `take=30`.<br><br>      If no value is specified for the `take` parameter, the default number of saved locations retrieved is `10`.<br><br>      You can use `sortBy` to sort your results. This is optional but if provided must be an array of properties you would like to sort by with a suffix of the sort order.<br><br>      For example `sortBy=name.asc`. If no order is specified the endpoint will default to ascending order.<br><br><br>      You can use `visibility` to get your private or public(shared by whole organization) saved locations. This is optional but if provided must be a valid value(public, private).<br><br>      *HINT: The `id` returned from this endpoint will be used as `savedLocationId` in some analysis endpoints*'
      operationId: PublicSavedLocationsController_findAll_v1
      parameters:
      - name: tags
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
      - name: addressTypes
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - office
            - hotel
            - event
            - restaurant
            - travel
            - warehouse
            - facility
            - parking
            - service_area
            - point_of_interest
            - retail
            - airport
            - military_base
            - other
      - name: sortBy
        required: false
        in: query
        description: Sort fields. Some fields may not be available for all organizations.
        schema:
          example:
          - name.asc
          - customerLocationId.asc
          - addressType.desc
          - change.desc
          - score.desc
          type: array
          items:
            type: string
      - name: visibility
        required: false
        in: query
        schema:
          type: string
          enum:
          - shared
          - private
      - name: page
        required: false
        in: query
        schema:
          minimum: 1
          default: 1
          type: number
      - name: take
        required: false
        in: query
        schema:
          minimum: 1
          maximum: 50
          default: 10
          type: number
      responses:
        '200':
          description: Successfully received model list
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PageDto'
                - properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/PublicSavedLocation'
      security:
      - ApiKey: []
      summary: Get All Saved Location
      tags:
      - Saved Locations
  /v1/public/saved-locations/tags:
    get:
      description: This endpoint returns all distinct saved location tags created by the user and their count.
      operationId: PublicSavedLocationsController_getSavedLocationTags_v1
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      security:
      - ApiKey: []
      summary: Get Saved Location Tags
      tags:
      - Saved Locations
  /v1/public/saved-locations/report:
    get:
      operationId: PublicSavedLocationsController_getSavedLocationReport_v1
      parameters:
      - name: fromDate
        required: false
        in: query
        schema:
          format: date-time
          type: string
      - name: toDate
        required: false
        in: query
        schema:
          format: date-time
          type: string
      - name: sourceIds
        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: radius
        required: true
        in: query
        schema:
          type: number
      - name: units
        required: true
        in: query
        description: 'NB: miles, kilometers and meters will be deprecated soon.'
        schema:
          type: string
          enum:
          - mi
          - km
          - m
          - miles
          - kilometers
          - meters
      - name: isGTM
        required: false
        in: query
        schema:
          default: true
          type: boolean
      - name: types
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - crime
            - unrest
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SavedLocationReport'
            text/csv:
              schema:
                type: string
          description: ''
        '401':
          description: Unauthorized. Your API Key may be invalid or expired.
        '500':
          description: Internal Server Error
      security:
      - ApiKey: []
      tags:
      - Saved Locations
  /v1/public/saved-locations/{id}:
    get:
      description: 'This endpoint allows you to get a saved location by it''s `id`.<br><br><br>      *HINT: The `id` returned from this endpoint will be used as `savedLocationId` in some analysis endpoints*'
      operationId: PublicSavedLocationsController_findOne_v1
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: number
      responses:
        '404':
          description: Saved location not found
      security:
      - ApiKey: []
      summary: Get Saved Location
      tags:
      - Saved Locations
    put:
      description: 'This endpoint allows you to update a saved location. Changes made to a saved location here will also be visible in your dashboard.<br><br><br>      *HINT: The `id` returned from this endpoint will be used as `savedLocationId` in some analysis endpoints*'
      operationId: PublicSavedLocationsController_update_v1
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLocationDto'
      responses:
        '404':
          description: Saved location not found
      security:
      - ApiKey: []
      summary: Update Saved Location
      tags:
      - Saved Locations
    delete:
      description: This endpoint allows you to delete a saved location. Changes made to a saved location here will also be visible in your dashboard.
      operationId: PublicSavedLocationsController_remove_v1
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: number
      responses:
        '200':
          description: ''
      security:
      - ApiKey: []
      summary: Delete Saved Location
      tags:
      - Saved Locations
components:
  schemas:
    PageMetaDto:
      type: object
      properties:
        page:
          type: number
        take:
          type: number
        itemCount:
          type: number
        pageCount:
          type: number
        hasPreviousPage:
          type: boolean
        hasNextPage:
          type: boolean
      required:
      - page
      - take
      - itemCount
      - pageCount
      - hasPreviousPage
      - hasNextPage
    UpdateLocationDto:
      type: object
      properties:
        tags:
          maxItems: 15
          type: array
          items:
            type: string
        name:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        address:
          type: string
        addressType:
          enum:
          - office
          - hotel
          - event
          - restaurant
          - travel
          - warehouse
          - facility
          - parking
          - service_area
          - point_of_interest
          - retail
          - airport
          - military_base
          - other
          type: string
        customerLocationId:
          type: string
        isPrivate:
          type: boolean
        radiusMeters:
          type: number
      required:
      - name
      - latitude
      - longitude
      - address
      - addressType
      - customerLocationId
      - isPrivate
      - radiusMeters
    PageDto:
      type: object
      properties:
        data:
          type: array
          items:
            type: array
        meta:
          $ref: '#/components/schemas/PageMetaDto'
      required:
      - data
      - meta
    SavedLocationTagsEntity:
      type: object
      properties:
        savedLocationId:
          type: number
        name:
          type: string
      required:
      - savedLocationId
      - name
    SavedLocationReport:
      type: object
      properties:
        Base Location ID:
          type: object
        Customer Location ID:
          type: string
        Location Name:
          type: string
        Latitude:
          type: object
        Longitude:
          type: object
        BaseScore:
          type: object
        Location Type:
          type: string
        Dataset From Date:
          type: string
        Dateset To Date:
          type: string
        Temporal Granularity:
          type: string
        All Crime:
          type: object
      required:
      - Base Location ID
      - Customer Location ID
      - Location Name
      - Latitude
      - Longitude
      - Location Type
      - Dataset From Date
      - Dateset To Date
      - Temporal Granularity
      - All Crime
    CreateLocationDto:
      type: object
      properties:
        tags:
          maxItems: 15
          type: array
          items:
            type: string
        name:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        address:
          type: string
        addressType:
          enum:
          - office
          - hotel
          - event
          - restaurant
          - travel
          - warehouse
          - facility
          - parking
          - service_area
          - point_of_interest
          - retail
          - airport
          - military_base
          - other
          type: string
        customerLocationId:
          type: string
        isPrivate:
          type: boolean
        radiusMeters:
          type: number
      required:
      - name
      - latitude
      - longitude
    PublicSavedLocation:
      type: object
      properties:
        id:
          type: number
        customerLocationId:
          type: string
        name:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        address:
          type: string
        addressType:
          enum:
          - office
          - hotel
          - event
          - restaurant
          - travel
          - warehouse
          - facility
          - parking
          - service_area
          - point_of_interest
          - retail
          - airport
          - military_base
          - other
          type: string
        tags:
          type: array
          items:
            $ref: '#/components/schemas/SavedLocationTagsEntity'
        isPrivate:
          type: boolean
        h3IdLvl8:
          type: string
          nullable: true
      required:
      - id
      - name
      - latitude
      - longitude
      - h3IdLvl8
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-KEY