The time reports API uses the Google Visualization API's query language to  run detailed reports on a user's team, company, as well as provider specific detail.

In order to use the reports API you need to understand the data model accessible as well as the supported Google query language elements.

Please see the oDesk Google Data Source Language page for a detailed description of what's available.

For more details around how to construct data parameters see the google documentation.

* Please note that you may get a report timeout if you select a large time period.

Generate Time Reports for a Specific Team

Time reports can be generated for a specific team, with or without detailed monetary information based on the relationship of the authorized user at the time the call is made and what information is included in the call.

If the provider_id fields (providers) are presented in the query, the caller must be a supervisor of the providers. If the provider_id is not provided in the query, the caller must have either Hiring Manager or Finance permission to the specified teams.

Parameters Details  

URL Parameters

• /hours
• Limits the query to hour specific elements and hides all financial details.

Optional GET Parameters 

• tqx
• The return format can be in either XML, JSON or CSV formatting: xml, json or csv. JSON is returned by default. Ex.: tqx=out:xml

Sample Google Query for Team Reports on hours only (/hours):

tq=SELECT worked_on, provider_id, provider_name, sum(hours) WHERE worked_on >= '2009-10-01' AND worked_on <= '2009-10-31'

Sample Google Query for Team Reports:

tq=SELECT worked_on, provider_id, provider_name, sum(hours) WHERE worked_on >= '2009-10-01' AND worked_on <= '2009-10-31' 

Return Data Details 

• Because the API uses Google's query language the label and data type are included in the response. For instance the above example returns the hours worked per day ordered by provider. The exact structure and data that is required can be specified in the query used in the API call.
• If the API call includes the /hours parameter less data is returned, if the /hours parameter is excluded ( /api/timereports/:version/companies/:companyid/teams/:teamid ) then the following fields are excluded from the results: charges, charges_online and charges_offline.

Generating Company Wide Reports

Time reports can be generated on a company-wide level. All time reports fields are supported on this level except earnings related fields. In order to access this API the authorized user needs either hiring or finance permissions to all teams within the company.

Parameter Details 

Optional GET Parameters:

• tqx
• The return format can be in either XML or JASON formatting: xml or json. JSON is returned by default. Ex.: tqx=out:xml

Sample Google Query:

tq=SELECT week_worked_on, assignment_team_id, sum(hours), sum(charges) WHERE worked_on > '2009-10-01' AND worked_on <= '2009-10-31'

Return Data Details

• Because the API uses Google's query language the label and data type are included in the response. For instance the above example returns the hours worked per day ordered by provider. The exact structure and data that is required can be specified in the query used in the API call.

Generating Agency Specific Reports

Time reports can be generated for an agency, in order to use this API the authorized user needs staffing manager permissions to the agency.

Parameter Details

Optional GET Parameters:

• tqx
• The return format can be in either XML or JASON formatting: xml or json. JSON is returned by default. Ex.: tqx=out:xml

Sample Google Query:

tq=SELECT week_worked_on, assignment_team_id, provider_id, assignment_name, sum(hours), sum(earnings) WHERE worked_on > '2009-10-01' AND worked_on <= '2009-10-31'

Return Data Details

• Because the API uses Google's query language the label and data type are included in the response. For instance the above example returns the hours worked per day ordered by provider. The exact structure and data that is required can be specified in the query used in the API call.

Generating Provider Specific Reports

This API allows callers to fetch data source of themselves. No monetary fields, such as charges or earnings, are supported. The caller of this API must be the provider himself.

Parameters Details

URL Parameters:

• /hours
• If the /hours parameter is used then only hour based reporting details are available, all financial details will be hidden.

Optional GET Parameters:

• tqx
• The return format can be in either XML or JASON formatting: xml or json. JSON is returned by default. Ex.: tqx=out:xml

Example Google Queries:

Google Query for hours specific report:

tq=SELECT worked_on, assignment_team_id, hours, task, memo WHERE worked_on > '2009-10-01' AND worked_on <= '2009-10-31'

Google Query for all available elements:

tq=SELECT worked_on, assignment_team_id, hours, earnings, earnings_offline, task, memo WHERE worked_on > '2009-10-01' AND worked_on <= '2009-10-31' 

Details on Return Data

• Because the API uses Google's query language the label and data type are included in the response. For instance the above example returns the hours worked per day ordered by provider. The exact structure and data that is required can be specified in the query used in the API call.
• If the /hours element is included then earnings, earnings_online and earnings_offline are not included in the available data set.