openapi: 3.0.3
info:
  title: Badger Maps Accounts Routes API
  description: 'REST API for Badger Maps, field sales route-planning and CRM software. The API lets teams programmatically manage accounts (customers), account locations, optimized routes, check-ins (served under the /appointments/ resource), and users. Base URL: https://badgerapis.badgermapping.com/api/2. All requests are authenticated with a token supplied in an `Authorization: Token <api_key>` header. API/Developer Key access is included with paid plans (max 25k requests per day, per team); the key must be enabled by contacting Badger Maps support (support@badgermapping.com).

    Endpoint paths, methods, and the core request/response fields below are grounded in Badger Maps'' published API Blueprint (Apiary). Fields marked "modeled" in descriptions are reasonable inferences where the public docs are thin and require an enabled key to verify exhaustively.'
  version: '2.0'
  contact:
    name: Badger Maps Support
    url: https://support.badgermapping.com
    email: support@badgermapping.com
servers:
- url: https://badgerapis.badgermapping.com/api/2
  description: Badger Maps API v2
security:
- tokenAuth: []
tags:
- name: Routes
  description: Optimized driving routes and their ordered waypoints.
paths:
  /routes/:
    get:
      operationId: listRoutes
      tags:
      - Routes
      summary: List routes
      description: Returns the authenticated user's routes (id, name, and route date).
      responses:
        '200':
          description: A list of routes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RouteSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /routes/{route_id}/:
    parameters:
    - $ref: '#/components/parameters/RouteId'
    get:
      operationId: getRoute
      tags:
      - Routes
      summary: Retrieve a route
      description: Returns a single route with its ordered waypoints. Each waypoint references an account location, its position in the sequence, and timing details.
      responses:
        '200':
          description: The requested route.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Route'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Unauthorized:
      description: Authentication is missing or the token is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Waypoint:
      type: object
      properties:
        position:
          type: integer
          description: Order of this stop in the route.
        customer_id:
          type: integer
        location:
          $ref: '#/components/schemas/Location'
        start_time:
          type: string
          description: Planned arrival/timing detail (modeled).
        duration:
          type: integer
          description: Planned stop duration in minutes (modeled).
    Location:
      type: object
      properties:
        id:
          type: integer
        address:
          type: string
        lat:
          type: number
          format: float
        lng:
          type: number
          format: float
    RouteSummary:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        route_date:
          type: string
          format: date
    Route:
      allOf:
      - $ref: '#/components/schemas/RouteSummary'
      - type: object
        properties:
          waypoints:
            type: array
            items:
              $ref: '#/components/schemas/Waypoint'
    Error:
      type: object
      properties:
        detail:
          type: string
        status:
          type: integer
  parameters:
    RouteId:
      name: route_id
      in: path
      required: true
      description: The route id.
      schema:
        type: integer
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Token authentication. Send `Authorization: Token <api_key>`. Contact Badger Maps support to have your API/Developer Key enabled.'