Job Search API

Use the Job Search API to submit job searches and return results from your website.

Prerequisite

Create a free Publisher account to receive a Publisher ID and access to job data. Once you create this account, Indeed provides reports and earnings for your traffic.

Search request example

The following example shows a search request for Java developers (q) in Austin, TX (l):

http://api.indeed.com/ads/apisearch?publisher=123412341234123&q=java+developer&l=austin%2C+tx&sort=&radius=&st=&jt=&start=&limit=&fromage=&filter=&latlong=1&co=us&chnl=&userip=1.2.3.4&useragent=Mozilla/%2F4.0%28Firefox%29&v=2

You must specify the following parameters in your search request:

Parameter Type Required Description
publisher string Yes Publisher ID. Indeed assigns the Publisher ID after you create a Publisher account. Locate this ID on the XML Feed tab of your Publisher account.
v int Yes Version of the API. You must set this value to 2.
userip string Yes The IP address of the end user who will view job results from your website.
useragent string Yes The browser of the end user who will view job results from your website. You can obtain this parameter using the User-Agent HTTP request header from the end user.

Refer to the complete list of parameters for more details on effectively customizing your search.

Search response examples

Note: If you don’t specify a response format, the API returns XML by default.

XML example

<response version="2">
    <query>java</query> 
    <location>austin, tx</location>
    <dupefilter>true</dupefilter> 
    <highlight>false</highlight> 
    <totalresults>547</totalresults> 
    <start>1</start>
    <end>10</end> 
    <radius>25</radius> 
    <pageNumber>0</pageNumber> 
    <results>
        <result>
            <jobtitle>Java Developer</jobtitle>
            <company>XYZ Corp.</company>
            <city>Austin</city>
            <state>TX</state>
            <country>US</country>
            <formattedLocation>Austin, TX</formattedLocation>
            <source>Dice</source>
            <date>Mon, 02 Aug 2017 16:21:00 GMT</date>
            <snippet>looking for an object-oriented Java Developer... 
               Java Servlets, HTML, JavaScript, AJAX, Struts, Struts2, 
               JSF) desirable. Familiarity with Tomcat and the Java...</snippet> 
            <url>http://www.indeed.com/viewjob?jk=12345&indpubnum=8343699265155203</url> 
            <onmousedown>indeed_clk(this,'0000');</onmousedown>
            <latitude>30.27127</latitude>
            <longitude>-97.74103</longitude>
            <jobkey>12345</jobkey>
            <sponsored>false</sponsored>
            <expired>false</expired>
            <formattedLocationFull>Austin, TX</formattedLocationFull>
            <formattedRelativeTime>11 hours ago</formattedRelativeTime>
        </result>
    </results>
</response>

JSON example

{  
    "version":2,
    "query":"java",
    "location":"austin, tx",
    "dupefilter":true,
    "highlight":false,
    "radius":25,
    "start":1,
    "end":10,
    "totalResults":547,
    "pageNumber":0,
    "results":[  
        {  
            "jobtitle":"Java Developer",
            "company":"XYZ Corp.,",
            "city":"Austin",
            "state":"TX",
            "country":"US",
            "formattedLocation":"Austin, TX",
            "source":"Dice",
            "date":"Mon, 02 Aug 2017 16:21:00 GMT",
            "snippet":"looking for an object-oriented Java Developer... Java Servlets,
              HTML, JavaScript, AJAX, Struts, Struts2, JSF) desirable. Familiarity with
              Tomcat and the Java...",
            "url":"http://www.indeed.com/viewjob?jk=12345&indpubnum=8343699265155203",
            "onmousedown":"indeed_clk(this, '0000');",
            "latitude":30.27127,
            "longitude":-97.74103,
            "jobkey":"12345",
            "sponsored":false,
            "expired":false,
            "indeedApply":true,
            "formattedLocationFull":"Austin, TX",
            "formattedRelativeTime":"11 hours ago"
        }
    ]
}

Request parameters

Parameter Type Required Description Default
publisherstringYesPublisher ID. Indeed assigns the Publisher ID after you create a Publisher account. Locate this ID on the XML Feed tab of your Publisher account.-----
vintYesVersion of the API. You must set this value to 2.-----
useripstringYesThe IP address of the end user who will view job results from your website.-----
useragentstringYesThe browser of the end user who will view job results from your website. You can obtain this parameter using the User-Agent HTTP request header from the end user.-----
formatstringNoOutput format of the API. You can specify xml or json.xml
callbackstringNoCallback. The name of JavaScript callback function for passing search results. This parameter applies only when format is json.

Note: For security reasons, you must restrict the callback name to letters, numbers, and the underscore character.
Empty
qstringNoQuery. By default, terms are ANDed.

Tip: To format the search words for q, perform your search from the Job Search page. The URL displays the expected formatting for this parameter. For example, q=developer or q=java+developer.
Empty. Searches all jobs.
lstringNoLocation. Use a postal code or a "city, state/province/region" combination. For example, l=Austin%2C+TX.

Tip: Use the Job Search or Advanced Job Search page and inspect the URL to see how to encode your parameter values.
Empty. Searches all locations.
sortstringNoSort by relevance or date.relevance
radiusintNoDistance from the search location (point-to-point aerial transit path, or "as the bird flies").

Note: The unit for this parameter is local to the country. For example, the default is 25 miles in the United States and 25 kilometers in the Netherlands.
25
ststringNo Site type. To show only jobs from job boards, use jobsite. For jobs from direct employer websites, use employer.Empty. Searches all websites.
jtstringNo Job type. You can specify fulltime, parttime, contract, internship, or temporary. Empty. Searches all job types.
startintNoStart returning jobs at this result number, beginning at 0.

Note: You can use the start and limit parameters for pagination.
0
limitintNoMaximum number of results to return per query. The maximum value is 25.

Note: You can use the start and limit parameters for pagination.
10
fromageintNoNumber of days since a job was published. If you specify 15, for example, the API searches jobs published only within the last 15 days. Empty. Searches jobs posted anytime.
highlightintNoHighlight query terms. If you specify 1, this parameter applies boldface to the terms present in q.0
filterintNoFilter out duplicate jobs. To turn this off, specify 0. 1
latlongintNoLatitude and longitude information. To return this information for each job result, set to 1.0
costringNoCountry to search. See Supported Countries for the complete list.us
chnlstringNoChannel name for grouping API requests. If you want to use this API for multiple websites, include a channel name here.Empty

Requirements

To use the Job Search API, implement the following requirements.

Display meaningful results

Include the following response data on your website to ensure relevant results:

  • Title

  • Location

  • Job description snippet

  • Company name

Enable click tracking

Your HTML markup must reference a JavaScript file for click tracking support.

Copy the following code and paste it into the <head> section of your web page:

<script type="text/javascript" src="//gdc.indeed.com/ads/apiresults.js"></script>

Include attribution to Indeed

You must use the following attribution when displaying Indeed’s job search results.

Copy and paste the following code near the search results on your web page:

<span id="indeed_at"><a href="http://www.indeed.com/" rell="nofollow" >jobs</a> by <a href="http://www.indeed.com/" rell="nofollow" title="Job Search"><img src="http://www.indeed.com/p/jobsearch.gif" style="border: 0; vertical-align: middle;" alt="Indeed job search"></a></span>

Note: You can customize the Indeed website URL in the previous code to point to any supported country site.

Include nofollow tag

Every Indeed job URL on your website should include a nofollow tag.

Example—shows the rel attribute for job result link on your site set to nofollow.

<a href="www.example.com/joburl" rel="nofollow">job title</a>

Make job requests in real time

Do not cache search results. Always make requests in real time when a job seeker completes a job search.

Do not cache the IP address for api.indeed.com and regularly resolve DNS.

Apply API to multiple websites

You can use the API on multiple websites and track the performance of each site independently. Indeed offers channel codes to allow you to track the performance of each site individually.

To track site performance using channels, complete the following steps:

  1. Add a channel code by logging in to your Publisher account and selecting XML Feed > Add new channel.

  2. Append the channel name to the API request that you add to each website. Use the format: &chnl=website1

Paginate results on multiple pages

You can use only one API request for each web page that features Indeed job results. To display results on multiple pages, create a request to paginate results on a new page. Use the start and limit parameters to specify the sequence of your results per page.

Example—shows 20 jobs from Indeed per web page:

Page 1 API request: &start=0&limit=20
Page 2 API request: &start=20&limit=20
Page 3 API request: &start=40&limit=20

Note: By default, the API displays 10 results, but you can specify a maximum of 25 results per page.

Specify userip and useragent

You must include the userip and useragent parameters in API requests.

Example—shows values for userip and useragent parameters from the example search request:

&userip=1.2.3.4&useragent=Mozilla/%2F4.0%28Firefox%29

Include onmousedown attribute

Each set of API search results includes a unique <onnousedown> identifier. You must include this identifier in all <a href> job links you display on your site to ensure clicks are accurately tracked.

XML example response

<onmousedown>indeed_clk(this,'0000');</onmousedown>

JSON example response

{"onmousedown" : "indeed_clk(this, '0000');"}

Your link

<a onmousedown="indeed_clk(this,'0000');" href="http://www.examplejobboard.com/job?id=15">
    Example Job Title
</a>