Using Live API Client-Side with jQuery
You can leverage the Live API to keep information on your webpage in sync with content from the Yext Knowledge Manager on both single-location and multi-location pages. You can retrieve specific fields, apply custom formatting, filter for certain locations, and much more!

NOTE: If you are looking to easily display a few pre-formatted fields, see the “Embed tags” section of our Knowledge Tags guide.

Obtaining your API key

To begin using the Live API, you will need to obtain an API key with the appropriate permissions.
  1. Create a new app and obtain your API key by following the steps in our Get Started guide.
  2. On the “Create New App” page, enter the required information and set:
    • the Permissions field to Read Only (important as your API key will be exposed in client-side code) and
    • the Endpoints field to Live API for consumer-facing webpages.
      • You can read more about the different APIs we offer on our Overview page.
NOTE: It may take 10-15 minutes for your Live API key to become active.

Calling the Live API

You can find more information about the endpoints in the Live API in Using the Live API.
For complete details about each call, see our Live API documentation.

Populating your webpage with information for one location

In addition to sending API requests with tools like Postman, you can also connect to the Live API via JavaScript (jQuery) and display attributes for one location on your webpage.
  1. Set up an API call using jQuery in your JavaScript file to pull one location:
     $(document).ready(function () {
     	apiKey = <YOUR_API_KEY>,
      	vParam = <YYYYMMDD>,
         locationID = <LOCATION_ID>,
     	 $.ajax({
        		type: 'GET',
        		url : 'https://liveapi.yext.com/v2/accounts/me/locations/'     
                    + locationID + '?api_key=' + apiKey + '&v=' + vParam,
        		success: function(data, textStatus, xhr){
         		// TODO: your callback function 
    // TIP: parse your response with: JSON.parse(xhr.responseText).response		
       		 }, error: function(xhr, textStatus, errorThrown) {
          			console.log('Unable to load data')
        		}
      	});
    });
    

  2. Populate your parameters:
    • API Key – (see instructions above for obtaining your API Key)
    • v parameter – the date you started your integration
    • Location ID – use the Store ID from Knowledge Manager for the location you want to return



  3. Parse the JSON response you receive from the API.
    • You can see an example response body in Using the Live API.
      var response = JSON.parse(xhr.responseText).response
      
      // Examples of grabbing individual values 
      var locationName = response.locationName
      var address = response.address
      

  4. Display the data on your webpage.
    • See the end of this guide for downloadable code examples.


Displaying data from multiple locations on your website

In this example, we’ll present locations in an easy-to-read format that links to individual location pages.

NOTE: This example uses Bootstrap 4, which you can include by following the directions in Bootstrap’s documentation.
  1. Set up an API call using jQuery in your JavaScript file to retrieve data from multiple locations.
     $(document).ready(function () {
     	apiKey = <YOUR_API_KEY>,
      	vParam = <YYYYMMDD>,
     	 $.ajax({
        		type: 'GET',
        		url : 'https://liveapi.yext.com/v2/accounts/me/locations'     
                    + '?api_key=' + apiKey + '&v=' + vParam,
        		success: function(data, textStatus, xhr){
         		// TODO: your callback function 
    // TIP: parse your response with: JSON.parse(xhr.responseText).response		
       		 }, error: function(xhr, textStatus, errorThrown) {
          			console.log('Unable to load data')
        		}
      	});
    });
    

  2. Populate your parameters:
    • API Key – (see instructions above for obtaining your API Key)
    • v parameter – the date you started your integration

  3. Create a callback function to parse and populate your information.

    1. You can set your callback function within the success brackets to:
      renderPage(JSON.parse(xhr.responseText).response);

    2. Define your callback function, code the HTML, and iterate through your locations.

      NOTE: This example uses Bootstrap Cards. For more information about Cards and Card Decks in Bootstrap, see Bootstrap’s documentation.
      // Build out the shell HTML and iterate through each location object
      function renderPage(answer) {
        var html = '<div class="row card-deck">'
      
      // iterate through each location 
        for (i = 0; i < answer.count; i++) {
          html += appendLocationCard(answer.locations[i]);
        }
      
        html += '</div>'
      // append the constructed HTML to your page
        $("#placeholder").append(html);
      
        return;
      }
      

    3. Add a function to append each location card to your page:
      // Create the HTML for each card
      function appendLocationCard(location) {
      
        var locationHtml = '<div class="col-md-4">'
        locationHtml += '<div class="card text-center mb-4">'
      
        locationHtml += '<div class="card-body">'
        locationHtml += '<h5 class="card-title">' + location.locationName + '</h5>'
        locationHtml += '<p class="card-text">' + location.address
        locationHtml += '<br>' + location.address2
        locationHtml += '<br>' + location.city + ' '+ location.state + ' ' + location.zip + '</p>'
        locationHtml += '<p>Call Us: <a href="tel:' + location.phone + '">' + location.phone + '</a></p>'
        locationHtml += '<a href=' + location.websiteUrl + ' class="btn btn-primary">Visit Website</a>'
        locationHtml += '</div>'
        
        locationHtml += '</div>

    You should now have all your locations shown as cards on your webpage.

Filtering

If you want to display only a particular set of stores, you can apply filters to your Live API call. For more information, see the "Using the Filters parameter" section of Using the Live API. Filters must be URL-encoded.
You can filter out closed locations by adding the following filter to your API call:
  • filters=[{“closed”:”false”}]
  • URL-encoded: %5B%7B%22closed%22%3A%22false%22%7D%5D
$(document).ready(function () {
  api_key = '<YOUR_API_KEY>',
  vparam = YYYYMMDD,
  // URL encoded filter for open locations
  filter = '%5B%7B%22closed%22%3A%22false%22%7D%5D',
  $.ajax({
    type: 'GET',
    url : 'https://liveapi.yext.com/v2/accounts/me/locations' + '?api_key=' + api_key + '&v=' + vparam + '&filters=' + filter,
    success: function(data, textStatus, xhr){
      renderPage(JSON.parse(xhr.responseText).response);
    }, error: function(xhr, textStatus, errorThrown) {
      console.log('Unable to load data')
    }
  });
});

/************************** 
You can also apply multiple filters, for example: open locations in the US:
[{"closed":"false"},{"countryCode":{"includes":["US"]}}]
     URL encoded: %5B%7B%22closed%22%3A%22false%22%7D%2C%7B%22countryCode%22%3A%7B%22includes%22%3A%5B%22US%22%5D%7D%7D%5D
**************************/

Adding Schema to Your Page

Schema markup is code added to your webpages to better enable search engines to classify your content and deliver relevant results to consumers. To learn more about schema and the types of data they can be applied to, visit schema.org.

Our recommended approach for adding schema to your webpage is to use Knowledge Tags. However, you can also leverage the Live API to generate schema from your information in Knowledge Manager by sending a request to the Locations Schema: Get endpoint.

Here's an example request in JavaScript to retrieve schema for a specific location:
$(document).ready(function () {
  locationID = '<LOCATION_ID>',
  api_key = '<YOUR_API_KEY>',
  vParam = 'YYYYMMDD',
  language = '2_CHARACTER_LANGUAGE_PROFILE', // Ex: ‘EN’
  $.ajax({
    type: 'GET',
    url : 'https://liveapi.yext.com/v2/accounts/me/locations/' + locationID + 
    '/profiles/' + language + '/schema'+ '?api_key=' + api_key + '&v=' + vParam,
    success: function(data, textStatus, xhr){
      renderSchema(JSON.parse(xhr.responseText).response);
    }, error: function(xhr, textStatus, errorThrown) {
      console.log('Unable to load data')
    }
  });
});
To finish, you can create the HTML structure for the schema and add it to your page's HTML. Here's an example that you can add to the previous JavaScript code sample:
function renderSchema(answer) {
    var html = '<script type="application/ld+json">'

    html += JSON.stringify(answer);

    html += '</script>'

    // Add it to your HTML
    $("#elementID").after(html)
  return;
 }

Downloadable code examples

You can find example code hosted on GitHub: