openapi: 3.0.3
info:
  title: TravelCenters of America Fuel Codes Locations API
  description: TravelCenters of America provides REST APIs for integrating with TA and Petro travel center operations. Available services include truck service work order management, retail location data, fuel codes, pricing, parking availability, and shower availability across the largest publicly traded full-service travel center network in the United States.
  version: v1.0.0
  contact:
    name: TravelCenters of America Developer Support
    url: https://www.ta-petro.com/developers/
  x-logo:
    url: https://www.ta-petro.com/logo.png
servers:
- url: https://api.accessta.com/v1
  description: TravelCenters of America Production API Server
security:
- ApiKeyAuth: []
tags:
- name: Locations
  description: Travel center location search and amenity data
paths:
  /locations:
    get:
      operationId: listLocations
      summary: List Locations
      description: Returns a list of TA, Petro, and TA Express travel center locations with amenity details. Filter by geographic proximity, brand, or amenity type.
      tags:
      - Locations
      parameters:
      - name: lat
        in: query
        required: false
        schema:
          type: number
          format: float
        description: Latitude for proximity search
      - name: lon
        in: query
        required: false
        schema:
          type: number
          format: float
        description: Longitude for proximity search
      - name: radius
        in: query
        required: false
        schema:
          type: number
          default: 50
        description: Search radius in miles
      - name: brand
        in: query
        required: false
        schema:
          type: string
          enum:
          - TA
          - Petro
          - TA Express
        description: Filter by travel center brand
      - name: state
        in: query
        required: false
        schema:
          type: string
        description: Filter by US state code (e.g., OH, TX)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
        description: Maximum locations to return
      responses:
        '200':
          description: Successful response with location list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /locations/{id}:
    get:
      operationId: getLocation
      summary: Get Location
      description: Returns detailed information for a specific travel center location including all amenities, fuel lanes, truck parking, and services.
      tags:
      - Locations
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Location identifier
      responses:
        '200':
          description: Successful response with location details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /locations/{id}/amenities:
    get:
      operationId: getLocationAmenities
      summary: Get Location Amenities
      description: Returns the full list of amenities available at a specific travel center location, including restaurants, fuel types, services, and facilities.
      tags:
      - Locations
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Location identifier
      responses:
        '200':
          description: Successful response with amenity list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmenityListResponse'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Amenity:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
        description:
          type: string
        available:
          type: boolean
    LocationListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Location'
        total:
          type: integer
    LocationResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Location'
    Location:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        brand:
          type: string
          enum:
          - TA
          - Petro
          - TA Express
        address:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
        lat:
          type: number
          format: float
        lon:
          type: number
          format: float
        phone:
          type: string
        hours:
          type: string
        truck_lanes:
          type: integer
        truck_parking_spaces:
          type: integer
        amenities:
          type: array
          items:
            type: string
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        code:
          type: integer
    AmenityListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Amenity'
  responses:
    Unauthorized:
      description: Unauthorized - invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API access token obtained via developer.accessta.com