Report Charges 
====

The usage endpoint is available at `public-api-usage.service.payscale.com <https://public-api-usage.service.payscale.com>`.  There are two endpoints:

* ``/usage`` - This endpoint returns a csv containing every logged request to the service, including information about whether that request was successful, the given inputs, and the given outputs.
* ``/usagestats`` - This endpoint returns a json object with the following fields:


Viewing Usage
~~~~~~~~~~~~~

To view fine-grained usage, download the CSV from the ``/usage`` endpoint. The purpose of this
endpoint is to allow users to explore their requests and responses, along with whether or not
those responses were considered successful and are billable.

The output ``usage.csv`` from this minimal application is ready to explore with Excel or any text editor,
and has the following columns:

* ``CLIENTID`` - the clientId associated with this request.
* ``REPORTID`` -
* ``REPORT_DATE`` - A timestamp indicating when the request was recorded in UTC.
* ``REPORT_TYPE`` - The type of report present in the request.
* ``REPORTRATING`` - The report rating, where ``0`` indicates a low-confidence report and ``1`` indicates a high-confidence report.
* ``REQUEST`` - A json object containing the received request.
* ``SUBMITTED_ANSWERS`` - A list of json objects mapping the received `QuestionId` to the selected `Value`, along with the `Type` of that `QuestionId`. These are submitted in the `Answers` entry of the request object.
* ``RESPONSE`` - A json object containing the content of the report associated with this request. If a single request contained two `RequestedReports`, they will be on separate lines in this csv.
* ``SUCCESSFUL`` - A boolean representing whether the report was successful (`True`) or not (`False`). Reports are only billable if this value is `True`.
* ``MONTH`` - The calendar month associated with this report, as report usage is billed monthly.
* ``YEAR`` - The year associated with this report.
* ``JOBTITLERATING`` - If applicable, the `JobTitleRating` associated with a the report. This is only present if `AutoResolveJobTitle` was set to `True` in the request.

A minimal python application to collect these results looks like the following:

.. code-block:: python

  import requests
  import time


  auth_url = 'https://accounts.payscale.com'
  get_token_url = f'{auth_url}/connect/token'
  client_id = '<client_id>'
  client_secret = '<client_secret>'

  # get oauth token using given clientId and clientSecret
  payload = {
      'grant_type': 'client_credentials',
      'scope': 'jobalyzer',
      'client_id': client_id,
      'client_secret': client_secret
  }
  token_response = requests.post(get_token_url, data=payload)
  token = None
  if token_response.status_code == 200:
      token = token_response.json()['access_token']
  else:
      print(f'failed to get token: {token_response.text}')

  usage_root_url = 'https://public-api-usage.service.payscale.com'
  usage_url = f'{usage_root_url}/usage'
  usage_stats_url = f'{usage_root_url}/usagestats'

  request_data = {
      'user': '<your-username>',
      'month': 'May', # casing does not matter here, but it must be the full name of the month.
      'year': 2021
  }

  # get the usage data and save to a csv
  headers = {'Authorization': f'Bearer {token}', 'accept': 'csv/text'}
  usage_response = requests.get(usage_url, headers=headers, params=request_data)

  if usage_response.status_code == 200:
      with(open('usage.csv', 'w')) as file:
          file.write(usage_response.text)


Viewing Usage Summary
~~~~~~~~~~~~~~~~~~~~~

In addition to the endpoint which returns the entirety of the requests and responses for this
billable month, there is also a summary endpoint which returns a summary of the usage.
This endpoint is available at ``/usagestats``.

.. code-block:: javascript

  {
      "usage": {
          "totalReports": <int>, // The total number of reports made in this time period
          "totalBillableReports": <int>, // The total number of billable (successful) reports made in this time period
          "clientId": <str>, // the clientId associated with these requests
          "successfulReports": {
              "skills": <int>, // The number of successful Skills reports
              "pay": <int>, // The number of successful Pay reports
              "yoe": <int> // The number of successful Years of Experience reports
          },
          "unsuccessfulReports": {
              "skills": <int>, // The number of unsuccessful Skills reports
              "pay": <int>, // The number of unsuccessful Pay reports
              "yoe": <int> // The number of unsuccessful Years of Experience reports
          }
      }
  }

A minimal python application to collect these results looks like the following:

.. code-block:: python

  import requests
  import time


  auth_url = 'https://accounts.payscale.com'
  get_token_url = f'{auth_url}/connect/token'
  client_id = '<client_id>'
  client_secret = '<client_secret>'

  # get oauth token using given clientId and clientSecret
  payload = {
      'grant_type': 'client_credentials',
      'scope': 'jobalyzer',
      'client_id': client_id,
      'client_secret': client_secret
  }
  token_response = requests.post(get_token_url, data=payload)
  token = None
  if token_response.status_code == 200:
      token = token_response.json()['access_token']
  else:
      print(f'failed to get token: {token_response.text}')

  usage_root_url = 'https://public-api-usage.service.payscale.com'
  usage_url = f'{usage_root_url}/usage'
  usage_stats_url = f'{usage_root_url}/usagestats'

  request_data = {
      'user': '<your-username>',
      'month': 'May', # casing does not matter here, but it must be the full name of the month.
      'year': 2021
  }

  # get the usage summary statistics and save to a json file
  headers = {'Authorization': f'Bearer {token}'}
  usage_stats_response = requests.get(usage_stats_url, headers=headers, params=request_data)

  if usage_stats_response.status_code == 200:
      with(open('usage_stats.json', 'w')) as file:
          file.write(usage_stats_response.text)

How Payscale Charges for Reports
~~~~

**Report Charges**

Payscale charges per report. Each report incurs a report credit. Clients purchase report credits which are consumed.

Some endpoints are able to generate multiple reports with a single request. For example:

   ``"requestedReports": ["yoe", "pay"]``

This counts as 2 reports because we're requesting both the YoE and Pay reports.

Other endpoints only generate one report at a time, for example, the ``impacts`` reports.

**Invalid Reports**

In some cases a report may not have enough data to be valid. In this case the "report rating" will be returned as zero and the user will not be charged for this report.

In other cases the "auto resolve job title" flag may be set. If a suitable job title cannot be found, the "job title rating" will be returned as zero and the user will not be charged for this report.

Please see https://developers.payscale.com/jobalyzer/ratings.html for more information.

**Avoiding Excess Charges**

Please see https://developers.payscale.com/jobalyzer/quickstart.html#integration for advice on initial report integration.