servicepytan.data module

Provides methods for simplified and opininated ways of retrieving data from the ServiceTitan API

class servicepytan.data.DataService(conn=None)

Bases: object

Primary class for executing data methods.

The DataService class retrieves the configuration file and authentication settings. The methods included are a selection of common data pulls with a simplified API generally based on retrieving data between a date range.

conn

a dictionary containing the credential config.

__init__(conn=None)

Inits DataService with configuration file and authentication settings.

get_jobs_completed_between(start_date, end_date, job_status=['Completed', 'Scheduled', 'InProgress', 'Dispatched'])

Retrieve all jobs completed between the start and end date.

Fetches jobs that were completed within the specified date range. Can filter by multiple job statuses simultaneously.

Parameters:

• start_date – Start date for the query (string or datetime object)

• end_date – End date for the query (string or datetime object)

• job_status – List of job statuses to include (default includes most common statuses)

Returns:

Combined list of all jobs matching the criteria

Return type:

list

Examples

>>> data_service = DataService(conn)
>>> jobs = data_service.get_jobs_completed_between("2024-01-01", "2024-01-31")
>>> completed_only = data_service.get_jobs_completed_between(
...     "2024-01-01", "2024-01-31", job_status=["Completed"]
... )

get_jobs_created_between(start_date, end_date)

Retrieve all jobs created between the start and end date.

Fetches jobs that were originally created within the specified date range, regardless of their current status or completion date.

Parameters:

• start_date – Start date for the query (string or datetime object)

• end_date – End date for the query (string or datetime object)

Returns:

List of all jobs created in the date range

Return type:

list

Examples

>>> data_service = DataService(conn)
>>> new_jobs = data_service.get_jobs_created_between("2024-01-01", "2024-01-31")

get_appointments_between(start_date, end_date, appointment_status=['Scheduled', 'Dispatched', 'Working', 'Done'])

Retrieve all appointments that start between the start and end date.

Fetches appointments scheduled to start within the specified date range. Can filter by multiple appointment statuses simultaneously.

Parameters:

• start_date – Start date for the query (string or datetime object)

• end_date – End date for the query (string or datetime object)

• appointment_status – List of appointment statuses to include

Returns:

Combined list of all appointments matching the criteria

Return type:

list

Examples

>>> data_service = DataService(conn)
>>> appointments = data_service.get_appointments_between("2024-01-01", "2024-01-31")
>>> scheduled_only = data_service.get_appointments_between(
...     "2024-01-01", "2024-01-31", appointment_status=["Scheduled"]
... )

get_sold_estimates_between(start_date, end_date)

Retrieve all sold estimates that were sold between the start and end date.

Fetches estimates that were marked as sold within the specified date range. Only includes active (not cancelled) estimates.

Parameters:

• start_date – Start date for the query (string or datetime object)

• end_date – End date for the query (string or datetime object)

Returns:

List of all sold estimates in the date range

Return type:

list

Examples

>>> data_service = DataService(conn)
>>> sold_estimates = data_service.get_sold_estimates_between("2024-01-01", "2024-01-31")

get_total_sales_between(start_date, end_date)

Retrieves total sales dollar amount between start and end date.

Calculates the total sales amount by summing all sold estimate items within the specified date range. This provides a quick way to get revenue totals for reporting.

Parameters:

• start_date – Start date for the query (string or datetime object)

• end_date – End date for the query (string or datetime object)

Returns:

Total sales amount for the period

Return type:

float

Examples

>>> data_service = DataService(conn)
>>> total_sales = data_service.get_total_sales_between("2024-01-01", "2024-01-31")
>>> print(f"Total sales: ${total_sales:,.2f}")

get_purchase_orders_created_between(start_date, end_date)

Retrieve all purchase orders created between the start and end date.

Fetches purchase orders that were created within the specified date range, useful for tracking procurement activity and spend.

Parameters:

• start_date – Start date for the query (string or datetime object)

• end_date – End date for the query (string or datetime object)

Returns:

List of all purchase orders created in the date range

Return type:

list

Examples

>>> data_service = DataService(conn)
>>> pos = data_service.get_purchase_orders_created_between("2024-01-01", "2024-01-31")

get_jobs_modified_between(start_date, end_date)

Retrieve all jobs modified between the start and end date.

Fetches jobs that were updated or modified within the specified date range, useful for tracking changes and updates to existing jobs.

Parameters:

• start_date – Start date for the query (string or datetime object)

• end_date – End date for the query (string or datetime object)

Returns:

List of all jobs modified in the date range

Return type:

list

Examples

>>> data_service = DataService(conn)
>>> modified_jobs = data_service.get_jobs_modified_between("2024-01-01", "2024-01-31")

get_employees(active='True')

Retrieve employee list.

Fetches the list of employees from ServiceTitan. Can filter to show only active employees or include inactive ones as well.

Parameters:

active – String indicating whether to show only active employees (“True” or “False”)

Returns:

List of employee records

Return type:

list

Examples

>>> data_service = DataService(conn)
>>> active_employees = data_service.get_employees()
>>> all_employees = data_service.get_employees(active="False")

get_technicians(active='True')

Retrieve technician list.

Fetches the list of technicians from ServiceTitan. Technicians are a subset of employees who perform field work.

Parameters:

active – String indicating whether to show only active technicians (“True” or “False”)

Returns:

List of technician records

Return type:

list

Examples

>>> data_service = DataService(conn)
>>> active_techs = data_service.get_technicians()
>>> all_techs = data_service.get_technicians(active="False")

get_tag_types(active='True')

Retrieve tag types list.

Fetches the list of tag types configured in ServiceTitan. Tag types are used to categorize and organize jobs, customers, and other entities.

Parameters:

active – String indicating whether to show only active tag types (“True” or “False”)

Returns:

List of tag type records

Return type:

list

Examples

>>> data_service = DataService(conn)
>>> tag_types = data_service.get_tag_types()

get_business_units(active='True')

Retrieve business units list.

Fetches the list of business units configured in ServiceTitan. Business units are used to organize operations by service type, location, or other criteria.

Parameters:

active – String indicating whether to show only active business units (“True” or “False”)

Returns:

List of business unit records

Return type:

list

Examples

>>> data_service = DataService(conn)
>>> business_units = data_service.get_business_units()