Fulcra Location API

openapi: 3.2.0
info:
  contact:
    email: contact@fulcradynamics.com
    name: Fulcra Dynamics
    url: https://www.fulcradynamics.com/
  description: REST API for interacting with the Fulcra Platform and Data Store
  termsOfService: https://www.fulcradynamics.com/legal/terms-of-use
  title: Fulcra Life Location API
  version: 1.0.0
servers:
- url: https://api.fulcradynamics.com
  description: Fulcra Life API
security:
- bearerAuth: []
tags:
- name: Location
paths:
  /data/v0/{fulcra_userid}/apple_location_updates:
    get:
      description: 'Retrieve the raw Apple location update samples for the specified

        user during the specified period of time.'
      operationId: get_apple_location_updates_data_v0__fulcra_userid__apple_location_updates_get
      parameters:
      - in: path
        name: fulcra_userid
        required: true
        schema:
          format: uuid
          title: Fulcra Userid
          type: string
      - description: The starting timestamp in ISO 8601 format (inclusive)
        in: query
        name: start_time
        required: true
        schema:
          description: The starting timestamp in ISO 8601 format (inclusive)
          examples:
          - '2023-02-01 00:00:00Z'
          format: date-time
          title: Start Time
          type: string
      - description: The ending timestamp in ISO 8601 format (exclusive)
        in: query
        name: end_time
        required: true
        schema:
          description: The ending timestamp in ISO 8601 format (exclusive)
          examples:
          - '2023-02-03 00:00:00Z'
          format: date-time
          title: End Time
          type: string
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Return Apple geo-location update samples for a user
      tags:
      - Location
  /data/v0/{fulcra_userid}/gmaps_location_updates:
    get:
      deprecated: true
      description: 'Retrieve the raw Apple location update samples for the specified

        user during the specified period of time.'
      operationId: get_gmaps_location_updates_data_v0__fulcra_userid__gmaps_location_updates_get
      parameters:
      - in: path
        name: fulcra_userid
        required: true
        schema:
          format: uuid
          title: Fulcra Userid
          type: string
      - description: The starting timestamp in ISO 8601 format (inclusive)
        in: query
        name: start_time
        required: true
        schema:
          description: The starting timestamp in ISO 8601 format (inclusive)
          examples:
          - '2023-02-01 00:00:00Z'
          format: date-time
          title: Start Time
          type: string
      - description: The ending timestamp in ISO 8601 format (exclusive)
        in: query
        name: end_time
        required: true
        schema:
          description: The ending timestamp in ISO 8601 format (exclusive)
          examples:
          - '2023-02-03 00:00:00Z'
          format: date-time
          title: End Time
          type: string
      - in: query
        name: fulcra_source_id
        required: false
        schema:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
          title: Fulcra Source Id
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Return Google Maps geo-location update samples for a user
      tags:
      - Location
  /data/v0/{fulcra_userid}/gmaps_location_updates/bounds:
    get:
      deprecated: true
      operationId: get_gmaps_location_updates_bounds_data_v0__fulcra_userid__gmaps_location_updates_bounds_get
      parameters:
      - in: path
        name: fulcra_userid
        required: true
        schema:
          format: uuid
          title: Fulcra Userid
          type: string
      - description: Filter against a fulcra source
        in: query
        name: source
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter against a fulcra source
          examples:
          - com.fulcradynamics.file_upload.<uuid>
          title: Source
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BoundsResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Return temporal bounds of Google Maps geo-location update samples
      tags:
      - Location
  /data/v0/{fulcra_userid}/location_at_time:
    get:
      operationId: get_closest_location_data_v0__fulcra_userid__location_at_time_get
      parameters:
      - in: path
        name: fulcra_userid
        required: true
        schema:
          format: uuid
          title: Fulcra Userid
          type: string
      - description: The timestamp in ISO 8601 format to request location for
        examples:
          example1:
            summary: 08:00:00 UTC on Feb 1 2023
            value: '2023-02-01T08:00:00Z'
          example2:
            summary: 00:00:00 (UTC-8 time zone) on Feb 1 2023
            value: '2023-02-01T00:00:00-08:00'
        in: query
        name: time
        required: true
        schema:
          description: The timestamp in ISO 8601 format to request location for
          examples:
          - '2023-02-01T08:00:00Z'
          - '2023-02-01T00:00:00-08:00'
          format: date-time
          title: Time
          type: string
      - description: The amount of time to look back (and forward, if the include_after parameter is true) for a sample.
        examples:
          example1:
            summary: two days
            value: 172800
        in: query
        name: window_size
        required: false
        schema:
          default: 172800
          description: The amount of time to look back (and forward, if the include_after parameter is true) for a sample.
          examples:
          - '172800'
          title: Window Size
          type: integer
      - description: When true, a sample that occurs after the requested time may be returned if it is the closest one.
        in: query
        name: include_after
        required: false
        schema:
          default: true
          description: When true, a sample that occurs after the requested time may be returned if it is the closest one.
          examples:
          - 'True'
          title: Include After
          type: boolean
      - description: When true, Fulcra will attempt to reverse geocode the location and include the location details in the results.
        in: query
        name: reverse_geocode
        required: false
        schema:
          default: false
          description: When true, Fulcra will attempt to reverse geocode the location and include the location details in the results.
          examples:
          - 'False'
          title: Reverse Geocode
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Gets the user's location at the specified time.
      tags:
      - Location
  /data/v0/{fulcra_userid}/location_updates:
    get:
      description: 'Retrieve the location update samples for the specified user

        during the specified period of time.'
      operationId: get_location_updates_data_v0__fulcra_userid__location_updates_get
      parameters:
      - in: path
        name: fulcra_userid
        required: true
        schema:
          format: uuid
          title: Fulcra Userid
          type: string
      - description: The starting timestamp in ISO 8601 format (inclusive)
        in: query
        name: start_time
        required: true
        schema:
          description: The starting timestamp in ISO 8601 format (inclusive)
          examples:
          - '2023-02-01 00:00:00Z'
          format: date-time
          title: Start Time
          type: string
      - description: The ending timestamp in ISO 8601 format (exclusive)
        in: query
        name: end_time
        required: true
        schema:
          description: The ending timestamp in ISO 8601 format (exclusive)
          examples:
          - '2023-02-03 00:00:00Z'
          format: date-time
          title: End Time
          type: string
      - description: A set of sources to use location samples from.
        examples:
          sample1:
            summary: ios
            value:
            - ios
        in: query
        name: location_sources
        required: false
        schema:
          default:
          - ios
          - google_maps
          description: A set of sources to use location samples from.
          items:
            $ref: '#/components/schemas/LocationSampleSource'
          title: Location Sources
          type: array
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Return geolocation update samples for a user
      tags:
      - Location
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    BoundsResponse:
      properties:
        end_date:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: the ending date/time of this data set
          title: End Date
        start_date:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: the starting date/time of this data set
          title: Start Date
      required:
      - start_date
      - end_date
      title: BoundsResponse
      type: object
    LocationSampleSource:
      description: Represents a source to retrieve location data from.
      enum:
      - ios
      - google_maps
      title: LocationSampleSource
      type: string
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT