swagger: "2.0"
info:
  version: 1.3.0
  title: "gov-gw"
  description: "Goverment Services Gateway"
  termsOfService: "http://taxnexus.net/terms/"
  contact:
    email: "noc@taxnexus.net"
  license:
    name: "Proprietary - Copyright (c) 2018-2021 by Taxnexus, Inc."
securityDefinitions:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-Key
schemes:
  - "http"
basePath: "/v1"
host: "localhost"
consumes:
  - "application/json"
produces:
  - "application/json"
parameters:
  addressQuery:
    name: address
    in: query
    description: Postal Address URL encoded; partial addresses allowed
    required: false
    type: string
  countryQuery:
    name: country
    in: query
    description: The Country abbreviation (2 char)
    required: false
    type: string
  limitQuery:
    description: How many objects to return at one time
    in: query
    name: limit
    type: number
    format: int32
    required: false
  offsetQuery:
    description: How many objects to skip? (default 0)
    in: query
    name: offset
    type: number
    format: int32
    required: false
  placeQuery:
    name: place
    in: query
    description: The City name (must be accompanied by State)
    required: false
    type: string
  stateQuery:
    name: state
    in: query
    description: The State or Province abbreviation (2 char)
    required: false
    type: string
responses:
  AccessForbidden:
    description: "Access forbidden, account lacks access"
    schema:
      $ref: "#/definitions/Error"
  Conflict:
    description: Conflict
    schema:
      $ref: "#/definitions/Error"
  InvalidDataError:
    description: Invalid data was sent
    schema:
      $ref: "#/definitions/InvalidError"
  NotFound:
    description: Resource was not found
    schema:
      $ref: "#/definitions/Error"
  ServerError:
    description: Server Internal Error
    schema:
      $ref: "#/definitions/Error"
  CoordinateResponse:
    description: Taxnexus Response
    schema:
      $ref: "#/definitions/CoordinateResponse"
  Unauthorized:
    description: "Access unauthorized, invalid API-KEY was used"
    schema:
      $ref: "#/definitions/Error"
  UnprocessableEntity:
    description: "Unprocessable Entity, likely a bad parameter"
    schema:
      $ref: "#/definitions/Error"

paths:
  /coordinates:
    get:
      security:
        - ApiKeyAuth: []
      summary: Get current tax rates for a coordinate
      operationId: getCoordinates
      description:
        Returns full tax information for a specific point on the map
        (tax situs). Uses existing Taxnexus Situs for lookup
        information.
      tags:
        - Tax Rates
      parameters:
        - $ref: "#/parameters/limitQuery"
        - $ref: "#/parameters/offsetQuery"
        - $ref: "#/parameters/addressQuery"
        - $ref: "#/parameters/placeQuery"
        - $ref: "#/parameters/stateQuery"
        - $ref: "#/parameters/countryQuery"
      responses:
        "200":
          $ref: "#/responses/CoordinateResponse"
        "401":
          $ref: "#/responses/Unauthorized"
        "403":
          $ref: "#/responses/AccessForbidden"
        "404":
          $ref: "#/responses/NotFound"
        "422":
          $ref: "#/responses/UnprocessableEntity"
        "500":
          $ref: "#/responses/ServerError"
definitions:
  Coordinate:
    properties:
      country:
        description: Geocoder Country
        type: string
      countryid:
        description: Taxnexus Country ID
        type: string
      county:
        description: Geocoder County
        type: string
      countyid:
        description: Taxnexus County ID
        type: string
      focus:
        description: Situs Focus for tax determination
        type: string
      formattedaddress:
        description: Formatted Address from Geocoder
        type: string
      id:
        description: Taxnexus Coordinate Record Id
        type: string
      isdistrict:
        description: Situs Incorporated District?
        type: boolean
      latitude:
        description: Latitude of coordinate
        type: number
      longitude:
        description: Longitude of coordinate
        type: number
      name:
        description: Coordinate Name from Search Text
        type: string
      neighborhood:
        description: Geocoder Neighborhood
        type: string
      place:
        description: Geocoder Place
        type: string
      placegeocode:
        description:
          The Taxnexus Geocode for this rated location (place or county)
        type: string
      placeid:
        description: Taxnexus Place ID
        type: string
      postalcode:
        description: Geocoder Postal Code
        type: string
      ref:
        description: External System reference ID
        type: string
      state:
        description: Geocoder State/Province name
        type: string
      stateid:
        description: Taxnexus State ID
        type: string
      status:
        description: The status of the coordinate in Taxnexus
        type: string
      street:
        description: Geocoder Street Name (only)
        type: string
      streetnumber:
        description: Geocoder Streen number
        type: string
      taxtypes:
        items:
          $ref: "#/definitions/TaxTypeID"
        type: array
      uuid:
        description: Unique identifier assigned at creation
        type: string
    type: object
  CoordinateRequest:
    description: An array of Coordinate Request Items
    properties:
      data:
        items:
          $ref: "#/definitions/CoordinateRequestItem"
        type: array
      meta:
        $ref: "#/definitions/RequestMeta"
    required:
      - meta
      - data
    type: object
  CoordinateRequestItem:
    description: A single Coordinate Request item
    properties:
      address:
        description: The address to be translated
        type: string
      ref:
        description: Source record reference
        type: string
    type: object
  CoordinateResponse:
    description: An array of Coordinate objects
    properties:
      data:
        items:
          $ref: "#/definitions/Coordinate"
        type: array
      meta:
        $ref: "#/definitions/ResponseMeta"
    type: object
  Error:
    properties:
      code:
        format: int32
        type: integer
      message:
        type: string
    type: object
  InvalidError:
    allOf:
      - $ref: "#/definitions/Error"
      - properties:
          details:
            items:
              type: string
            type: array
        type: object
  Pagination:
    properties:
      limit:
        format: int32
        type: integer
      pagesize:
        format: int32
        type: integer
      poffset:
        format: int32
        type: integer
      setsize:
        format: int32
        type: integer
    type: object
  RequestMeta:
    properties:
      TaxnexusAccount:
        description: Taxnexus Account Number of the Reseller or OEM
        type: string
    required:
      - TaxnexusAccount
    type: object
  ResponseMeta:
    properties:
      contact:
        description: Microservice Contact Info
        type: string
      copyright:
        description: Copyright Info
        type: string
      license:
        description: License Information and Restrictions
        type: string
      operationid:
        description: Operation ID
        type: string
      pagination:
        $ref: "#/definitions/Pagination"
      requestip:
        description: Request IP Address
        type: string
      requesttype:
        description: Request Type
        type: string
      requesturl:
        description: Request URL
        type: string
      serverinfo:
        description: Data Server Info
        type: string
      serverresponsetime:
        description: Data Server Response Time (ms)
        type: string
      servertimestamp:
        description: Backend Server Timestamp
        type: string
      TaxnexusAccount:
        description:
          Taxnexus Account Number used for recording transactions
        type: string
    type: object
  TaxTypeID:
    properties:
      taxtypeid:
        type: string
