The search/providers method is an Elance Developer API Search method that returns a list of providers who match the supplied set of keywords.

Keyword searches are performed against all text fields of an Elance provider record. Only records that contain all of the specified keywords will be returned.

The response for each provider includes their basic personal information, their rate, and their earnings and ratings within their category of service. If a provider belongs to more than one category, the method will return one provider object per category. For example, if a provider named ProviderUno belongs to both the "Web & Programming" category and the "Design & Multimedia" category, search/providers will return two records for ProviderUno. Each record will have different values of the category property, and different roll-up information for properties such as earnings6Months, feedback6Months, and elanceLevel.

Results are returned in fixed pages of 25 records each. By default, the first page of results is returned with an initial request; additional pages are requested by issuing subsequent requests on the same search with the page query string parameter. Results must be presented to end users in the same order as returned by the Search methods. Re-ordering the results is considered a violation of the Elance Developer API Terms of Service.

search/providers is a public method. It requires a valid Elance Developer API key, but does not require HTTP authentication. It is invoked using an HTTP GET request.

This method can return either straight JSON data or a Javascript callback. The name of the callback is specified using the jsonp query string parameter.

For more information on the format of an Elance Developer API request, see Getting Started.

tableofcontents_number_textOptional Query String Parameters

Parameter Description
keywords A space-delimited list of keywords to search. If omitted, this method returns a list of all active providers.
sortCol

The property by which to sort results. Valid values are:

earnings
feedback
level

The default is level.

sortOrder Sort the results in ascending or descending order. If this parameter is specified without sortCol, it is ignored. Valid values are:

asc
desc

The default is desc.

page The requested page of result sets, in sort order, numbered beginning from 1. Default is 1. If this number exceeds the value of the response property totalPages, the response contains zero results.
catFilter A positive integer representing a category ID that restricts search results to providers who belong to the specified category. A list of valid category IDs and associated names is available through the util/getCategories method. If the value of catFilter does not correspond to an existing category ID, the method returns an empty result set.
subcatFilter A positive integer representing a subcategory ID that restricts search results to providers who belong to the specified subcategory. A list of valid subcategory IDs and associated names is available through the util/getCategories method. If the value of subcatFilter does not correspond to an existing category ID, the method returns an empty result set.

tableofcontents_number_textResponse Data Description

For JSON responses, unless otherwise noted, all parameters are returned as JSON string types. The value in the Data Type column denotes the type to which the property can safely be cast.

Property Data Type Description
totalResults integer The total number of providers returned by this search request.
totalPages integer (JSON number) The total number of page results available.
page integer (JSON number) The current page of results.
numResults integer The number of records in the current page. May be less than 25 when the last page of data is returned.
pageResults array of Profile objects The ordered set of results. Individual jobs are returned as child objects of pageResults labeled by their sort order within the page, starting from 0.

tableofcontents_number_textProfile Objects

The following table defines the structure of a Profile object.

Property Data Type Description
userId integer The unique integer ID assigned to the provider by Elance.
userName string The unique user name chosen by the provider.
businessName string The name of the provider's business, as displayed on the provider's profile.
tagLine string A short phrase selected by the provider that summarizes their services.
hourlyRate integer The minimum hourly rate charged by the provider.
city string The provider's primary city.
state string The provider's primary state or province.
country string The provider's primary country of business.
earnings6Months integer The provider's total Elance earnings in the past six months for the specified category.
feedback6Months integer The total number of feedback reported received by provider on Elance in the past six months for the specified category.
posFeedback6Months integer The percentage of positive feedback received by the provider in the past six months for the specified category.
avgFeedbackScore6Months decimal The average feedback score obtained by the provider in the past six months for the specified category. Feedback scores range between 1 and 5, with 5 being the highest.
earnings12Months integer The provider's total Elance earnings in the past 12 months for the specified category.
feedback12Months integer The total number of feedback reported received by provider on Elance in the past 12 months for the specified category.
posFeedback12Months integer The percentage of positive feedback received by the provider in the 12 six months for the specified category.
avgFeedbackScore12Months decimal The average feedback score obtained by the provider in the past 12 months for the specified category. Feedback scores range between 1 and 5, with 5 being the highest.
elanceLevel integer The provider's level ranking on Elance, which reflects marketing activity, completed jobs, and client reviews. Relative to the specified category.
category string The category under which the provider provides services.
logo   The URL to the provider's logo, as displayed in search results. The dimensions of this image are always 40px by 50px. The image format is either JPEG or GIF (animated GIF is not supported).
providerProfileURL URL The URL to the provider's full profile on Elance.

tableofcontents_number_textRequest/Response Examples in JSON

tableofcontents_number_textRetrieve a List of Providers by Keywords

The following example HTTP GET request demonstrates retrieving a list of all providers on the Elance system whose profiles contain the term "technical" and "writer." Results are sorted by earnings; since a sortOrder parameter isn't specified, they are sorted in descending order, with the highest earners listed first. This example uses the curl command line utility.

tableofcontents_number_textRequest

curl "http://api.elance.com/api/search/providers?eauth_consumer_key=8dfc476c57fee5c7dc08cc0f1d5a0fcdab409b3c&keywords=technical%20writer&sortCol=earnings"

tableofcontents_number_textResponse

 {   
    "api": "search\/providers",  
	"apiVersion": 1,   
	"rcode": 1,   
	"data": {     
		"totalResults": "84729",     
		"totalPages": 3390,     
		"page": 1,     
		"numResults": "25",     
		"pageResults": {       
			"0": {         
				"userId": "300723",         
				"userName": "providerUno",         
				"businessName": "Provider Uno",         
				"tagLine": "For all your programming and technical writer needs!",         
				"hourlyRate": "20.0",         
				"city": "Johannesburg",         
				"state": "South Africa",         
				"country": "South Africa",         
				"earnings6Months": "455288",         
				"feedback6Months": "16",         
				"posFeedback6Months": "100",         
                                "avgFeedbackScore6Months": "4.9",
                                "earnings12Months": "1176954",
                                "feedback12Months": "43",
                                "posFeedback12Months": "95",
                                "avgFeedbackScore12Months": "4.8",      
				"category": "Web & Programming",         
				"logo": "http:\/\/www.elance.com\/uploads\/00\/00\/17323925\/provideruno.jpg",         
				"providerProfileURL": "http:\/\/www.elance.com\/provprofile?view_person=provideruno"       
			},       
			"1": {         
				"userId": "1341296",         
				"userName": "MegaDevsInc",         
				"businessName": "MegaDevs Writing Agency",         
				"tagLine": "No technical writer job is too large for MegaDevs.",         
				"hourlyRate": null,         
				"city": "Oxford",         
				"state": "MS",         
				"country": "United States",         
				"earnings6Months": "24038",         
				"feedback6Months": "5",         
				"posFeedback6Months": "100",
                                "avgFeedbackScore6Months": "4.9",
                                "earnings12Months": "1176954",
                                "feedback12Months": "43",
                                "posFeedback12Months": "95",
                                "avgFeedbackScore12Months": "4.8",               
				"category": "Engineering & Manufacturing",         
				"logo": "http:\/\/www.elance.com\/uploads\/00\/00\/12948376\/uts_logo_2007-50_x_45.jpg",         
				"providerProfileURL": "http:\/\/www.elance.com\/provprofile?view_person=megadevsinc"       
			},       
			"2": {         
				"userId": "180804",         
				"userName": "oliviatremor",         
				"businessName": "Olivia Tremor",         
				"tagLine": "Pens at the Ready and Under Control...",         
				"hourlyRate": null,         
				"city": "Vancouver",         
				"state": "British Columbia",         
				"country": "Canada",         
				"earnings6Months": "75896",         
				"feedback6Months": "78",         
				"posFeedback6Months": "97",
                                "avgFeedbackScore6Months": "4.9",
                                "earnings12Months": "1176954",
                                "feedback12Months": "43",
                                "posFeedback12Months": "95",
                                "avgFeedbackScore12Months": "4.8",      
				"category": "Writing & Translation",         
				"logo": "http:\/\/www.elance.com\/uploads\/00\/00\/12552406\/oliviatremor.png",         
				"providerProfileURL": "http:\/\/www.elance.com\/provprofile?view_person=oliviatremor"       
			} // Additional records omitted...
		}     
    }    
}

tableofcontents_number_textError Codes

For a list of possible errors, see Common API Error Codes. The format of error responses is specified in the Getting Started page.