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.

 

 

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

 

• :companyid
  • The company of the accessing team.
• :teamid
  • A team that the authorized user has access to.
• /hours
  • Limits the query to hour specific elements and hides all financial details.

 

GET Parameters

 

• tq
  • The Google query goes here. 
• tqx
  • The return format can be in either XML or JASON formatting: xml or json. JSON is returned by default.

 

 

 

Note: The query string given in the tq parameter in the following APIs must be encoded. See Google Query Language Reference - Setting the Query in the Data Source URL for more detail.

 

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), 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.
• 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 

 

URL Parameters: 

 

• :companyid
  • The company of the accessing team.

 

GET Parameters:

 

• tq
  • The Google query goes here, see the example below.
• tqx
  • The return format can be in either XML or JASON formatting: xml or json. JSON is returned by default.

 

Sample Google Query:

 

 

Note: The query string given in the tq parameter in the following APIs must be encoded. See Google Query Language Reference - Setting the Query in the Data Source URL for more detail.

 

 

 

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

 

URL Parameters:

• :companyid
  • The company of the accessing team.
• :agencyid
  • One of the agencies the authorized user has access to.

 

GET Parameters:

• tq
  • The Google query goes here, see the example below.
• tqx
  • The return format can be in either XML or JASON formatting: xml or json. JSON is returned by default.

 

 

Sample Google Query:

 

Note: The query string given in the tq parameter in the following APIs must be encoded. See Google Query Language Reference - Setting the Query in the Data Source URL for more detail.

 

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:

 

• :providerid
  •  The provider id of the authorized user.
• /hours
  • If the /hours parameter is used then only hour based reporting details are available, all financial details will be hidden.

 

GET Parameters:

 

• tq
  • The Google query goes here, see the example below.
• tqx
  • The return format can be in either XML or JASON formatting: xml or json. JSON is returned by default.

 

 

Example Google Queries:

 

Note: The query string given in the tq parameter in the following APIs must be encoded. See Google Query Language Reference - Setting the Query in the Data Source URL for more detail.

 

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.