Using the Live API
As part of our offering, Yext has a set of highly available, low-latency endpoints, which are perfect to power mobile apps or store locators. You have the ability to retrieve only certain location fields, filter your locations by field values, find locations within a radius of an address, and much more!

Get all locations

To retrieve a list of all the locations in an account, you would make the following call:

GEThttps://liveapi.yext.com/v2/accounts/me/locations?api_key=[API_KEY]&v=YYYYMMDD


Response Body:
{
  "meta": {
    "uuid": "5be852f3-f05f-4e55-bff6-101f9df1c2c5",
    "errors": []
  },
  "response": {
    "count": 4,
    "locations": [
      {
        "id": "3818283",
        "timestamp": 1497988041389,
        "accountId": "1242569",
        "locationName": "Yext",
        "address": "48 Warwick St.",
        "address2": "Office 410",
        "city": "London",
        "state": "Gt Lon",
        "zip": "W1B 5AW",
        "countryCode": "GB",
        "language": "en",
        "suppressAddress": false,
        "phone": "2037052290",
        "isPhoneTracked": false,
        "categoryIds": [
          "668"
        ],
        "featuredMessage": "Call Today",
        "websiteUrl": "https://locations.yext.com/gb/gt-lon/london/48-warwick-st-.html",
        "description": "Yext is the global location data management leader, and our mission is to help people Go Places™",
        "yextDisplayLat": 51.5107082,
        "yextDisplayLng": -0.1377925,
        "folderId": "107506",
        "customFields": {
          "15989": "Text",
          "15990": "6412",
          "15991": [
            "6414",
            "6415"
          ],
          "15992": "true"
        },
        "labelIds": [],
        "menusLabel": "",
        "menuIds": [],
        "bioListsLabel": "",
        "bioListIds": [],
        "productListsLabel": "",
        "productListIds": [],
        "eventListsLabel": "",
        "eventListIds": [],
        "locationType": "LOCATION",
        "uberLinkRaw": "https://m.uber.com/ul/?client_id=KXQcwoj2Zb8ymDzKgVgbIaDE5iAE_TAj&action=setPickup&pickup=my_location&dropoff%5Bnickname%5D=Yext&dropoff%5Blatitude%5D=51.5107082&dropoff%5Blongitude%5D=-0.1377925&dropoff%5Bformatted_address%5D=48%20Warwick%20St.%2COffice%20410%2CLondon%2CGt%20Lon",
        "isoRegionCode": "LND"
      },
      {
        "id": "3818284",
        "timestamp": 1497988041389,
        "accountId": "1242569",
        "locationName": "Yext",
        "address": "500 West Madison St.",
        "address2": "Suite 2810",
        "city": "Chicago",
        "state": "IL",
        "zip": "60661",
        "countryCode": "US",
        "language": "en",
        "suppressAddress": false,
        "phone": "2129943900",
        "isPhoneTracked": false,
        "categoryIds": [
          "668"
        ],
        "featuredMessage": "Call Today",
        "websiteUrl": "https://locations.yext.com/us/il/chicago/500-west-madison-st-.html",
        "description": "Yext is the global location data management leader, and our mission is to help people Go Places™",
        "yextDisplayLat": 41.8822187,
        "yextDisplayLng": -87.6405296,
        "yextRoutableLat": 41.881877,
        "yextRoutableLng": -87.640418,
        "folderId": "0",
        "customFields": {
          "15989": "Text",
          "15990": "6412",
          "15991": [
            "6414",
            "6415"
          ],
          "15992": "true"
        },
        "labelIds": [],
        "menusLabel": "",
        "menuIds": [],
        "bioListsLabel": "",
        "bioListIds": [],
        "productListsLabel": "",
        "productListIds": [],
        "eventListsLabel": "",
        "eventListIds": [],
        "locationType": "LOCATION",
        "uberLinkRaw": "https://m.uber.com/ul/?client_id=KXQcwoj2Zb8ymDzKgVgbIaDE5iAE_TAj&action=setPickup&pickup=my_location&dropoff%5Bnickname%5D=Yext&dropoff%5Blatitude%5D=41.881877&dropoff%5Blongitude%5D=-87.640418&dropoff%5Bformatted_address%5D=500%20West%20Madison%20St.%2CSuite%202810%2CChicago%2CIL",
        "isoRegionCode": "IL"
      },
      {
        "id": "3818285",
        "timestamp": 1494541585402,
        "accountId": "1242569",
        "locationName": "Yext",
        "address": "1 Madison Ave",
        "address2": "5th Floor",
        "city": "New York",
        "state": "NY",
        "zip": "10010",
        "countryCode": "US",
        "language": "en",
        "suppressAddress": false,
        "phone": "8884442988",
        "isPhoneTracked": false,
        "localPhone": "2128136543",
        "categoryIds": [
          "668"
        ],
        "featuredMessage": "Call Today",
        "websiteUrl": "https://locations.yext.com/us/ny/new-york/1-madison-ave.html",
        "description": "Yext is the global location data management leader, and our mission is to help people Go Places™",
        "yextDisplayLat": 40.7411107,
        "yextDisplayLng": -73.987448,
        "yextRoutableLat": 40.741199,
        "yextRoutableLng": -73.98774,
        "folderId": "0",
        "labelIds": [],
        "menusLabel": "",
        "menuIds": [],
        "bioListsLabel": "",
        "bioListIds": [],
        "productListsLabel": "",
        "productListIds": [],
        "eventListsLabel": "",
        "eventListIds": [],
        "locationType": "LOCATION",
        "uberLinkRaw": "https://m.uber.com/ul/?client_id=KXQcwoj2Zb8ymDzKgVgbIaDE5iAE_TAj&action=setPickup&pickup=my_location&dropoff%5Bnickname%5D=Yext&dropoff%5Blatitude%5D=40.741199&dropoff%5Blongitude%5D=-73.98774&dropoff%5Bformatted_address%5D=1%20Madison%20Ave%2C5th%20Floor%2CNew%20York%2CNY",
        "isoRegionCode": "NY"
      },
      {
        "id": "3818282",
        "timestamp": 1497984174774,
        "accountId": "1242569",
        "locationName": "Yext",
        "address": "7900 Westpark Drive",
        "address2": "Suite T200",
        "city": "McLean",
        "state": "VA",
        "zip": "22102",
        "countryCode": "US",
        "language": "en",
        "suppressAddress": false,
        "phone": "8884442988",
        "isPhoneTracked": false,
        "localPhone": "6467624579",
        "categoryIds": [
          "668"
        ],
        "featuredMessage": "Call Now!",
        "websiteUrl": "https://locations.yext.com/us/va/mclean/7900-westpark-drive.html",
        "hours": "1:10:30:0:00,2:10:30:0:00,3:10:30:0:00,4:10:30:0:00,5:10:30:0:00,6:10:30:1:00,7:10:30:1:00",
        "googleProfilePhoto": {
          "url": "http://a.mktgcdn.com/p/aVB6C01KuagkgVfCUkjSXzNTErYhe_qvmuxaazJ-tcs/250x250.png",
          "description": "description",
          "alternateText": "Alt Text",
          "width": 250,
          "height": 250
        },
        "walkableLat": 42.450019850144415,
        "walkableLng": -83.340731151402,
        "pickupLat": 42.4558869049193,
        "pickupLng": -83.34606556221843,
        "dropoffLat": 42.45576025349632,
        "dropoffLng": -83.3472671918571,
        "yextDisplayLat": 38.9243492,
        "yextDisplayLng": -77.2167465,
        "yextRoutableLat": 38.924361,
        "yextRoutableLng": -77.217774,
        "yextWalkableLat": 38.92416770721901,
        "yextWalkableLng": -77.21700652968138,
        "yextPickupLat": 38.92406337213516,
        "yextPickupLng": -77.2169180167839,
        "yextDropoffLat": 38.92427204214947,
        "yextDropoffLng": -77.21714868675917,
        "brands": [
          "Hello",
          "World"
        ],
        "folderId": "0",
        "closed": {
          "isClosed": false
        },
        "instagramHandle": "yext",
        "labelIds": [],
        "menusLabel": "",
        "menuIds": [],
        "bioListsLabel": "",
        "bioListIds": [],
        "productListsLabel": "",
        "productListIds": [],
        "eventListsLabel": "",
        "eventListIds": [],
        "locationType": "LOCATION",
        "uberLinkRaw": "https://m.uber.com/ul/?client_id=KXQcwoj2Zb8ymDzKgVgbIaDE5iAE_TAj&action=setPickup&pickup=my_location&dropoff%5Bnickname%5D=Yext&dropoff%5Blatitude%5D=38.92427204214947&dropoff%5Blongitude%5D=-77.21714868675917&dropoff%5Bformatted_address%5D=7900%20Westpark%20Drive%2CSuite%20T200%2CMcLean%2CVA",
        "isoRegionCode": "VA"
      }
    ]
  }
}

NOTE: To ensure rapid response times, the response is automatically paginated to have 10 locations per page by default. Using limit and offset parameters, it is possible to customize how many locations are returned at once and paginate through the results. Each page can include up to 50 locations.

Using the Filter parameter

The Live API’s Locations: List and Locations: GeoSearch endpoints give you the ability to filter your locations by field values. One common example would be to filter out any location have the closed field set to true. The URL would be formatted as follows:

GEThttps://liveapi.yext.com/v2/accounts/me/locations?api_key=[API_KEY]&v=YYYYMMDD&filters=[{“closed”:”false”}]


Some filters allow you to filter by multiple values. The example below returns all locations that have a countryCode that is not US or GB.

[{“countryCode”: {“notIncludes”: [“US”,”GB”]}}]

It is possible to combine as many different filters as desired. The below example returns results that are not closed and are not in the United States.

[{“closed”:”false”},{“countryCode”: {“notIncludes”: [“US”]}}]

Using the Yext internal folder ID values, it is also possible to filter based on folders:

[{“folder”:107506}]

Another common use case for filters is to filter on any number of internal custom fields. Custom fields can be set up to store any kind of data, and all fields can be filtered against. Some common fields and example filters appear below.
  • Single Option: [{“custom15990”:{“is”: 6412}}]
  • Text: [{“custom15989”:{“contains”: [“text”]}}]
  • Multi-option: [{“custom15991”:{“includes”: [“6414″,”6415”]}}]
  • Boolean: [{“custom15992″:”true”}]

Using the Fields parameter

If you would only like to retrieve certain fields for every location, you can use the fields parameter. For instance, if you only wanted the locationName and address fields returned, the request URL and response would be as follows:

GEThttps://liveapi.yext.com/v2/accounts/me/locations?api_key=[API_KEY]&v=YYYYMMDD&fields=locationName,address


Response Body:
{
  "meta": {
    "uuid": "d83fea05-6819-4e8b-8b0a-e61438ad91fd",
    "errors": []
  },
  "response": {
    "count": 4,
    "locations": [
      {
        "locationName": "Yext",
        "address": "48 Warwick St."
      },
      {
        "locationName": "Yext",
        "address": "500 West Madison St."
      },
      {
        "locationName": "Yext",
        "address": "1 Madison Ave"
      },
      {
        "locationName": "Yext",
        "address": "7900 Westpark Drive"
      }
    ]
  }
}

Get one location

To retrieve just one location, simply append the id of that location to the end of the URL path, and the response body will return the requested location.

GEThttps://liveapi.yext.com/v2/accounts/me/locations/[LOCATION_ID]?api_key=[API_KEY]&v=YYYYMMDD


Response Body:
{
  "meta": {
    "uuid": "237b20ac-ff75-4b31-99d9-b21ea8934773",
    "errors": []
  },
  "response": {
    "id": "3818283",
    "timestamp": 1497988041389,
    "accountId": "1242569",
    "locationName": "Yext",
    "address": "48 Warwick St.",
    "address2": "Office 410",
    "city": "London",
    "state": "Gt Lon",
    "zip": "W1B 5AW",
    "countryCode": "GB",
    "language": "en",
    "suppressAddress": false,
    "phone": "2037052290",
    "isPhoneTracked": false,
    "categoryIds": [
      "668"
    ],
    "featuredMessage": "Call Today",
    "websiteUrl": "https://locations.yext.com/gb/gt-lon/london/48-warwick-st-.html",
    "description": "Yext is the global location data management leader, and our mission is to help people Go Places™",
    "yextDisplayLat": 51.5107082,
    "yextDisplayLng": -0.1377925,
    "folderId": "107506",
    "customFields": {
      "15989": "Text",
      "15990": "6412",
      "15991": [
        "6414",
        "6415"
      ],
      "15992": "true"
    },
    "labelIds": [],
    "menusLabel": "",
    "menuIds": [],
    "bioListsLabel": "",
    "bioListIds": [],
    "productListsLabel": "",
    "productListIds": [],
    "eventListsLabel": "",
    "eventListIds": [],
    "locationType": "LOCATION",
    "uberLinkRaw": "https://m.uber.com/ul/?client_id=KXQcwoj2Zb8ymDzKgVgbIaDE5iAE_TAj&action=setPickup&pickup=my_location&dropoff%5Bnickname%5D=Yext&dropoff%5Blatitude%5D=51.5107082&dropoff%5Blongitude%5D=-0.1377925&dropoff%5Bformatted_address%5D=48%20Warwick%20St.%2COffice%20410%2CLondon%2CGt%20Lon",
    "isoRegionCode": "LND"
  }
}

GeoSearch

The Locations: GeoSearch endpoint is used to return locations that are within a certain radius of a specified address. The response is ordered by proximity to the address and restricted to the given radius. The values for the location can be specified in one of two ways:
  • Latitude and longitude: The latitude and longitude of the point, separated by a comma (e.g., 40.740957,-73.987565)
  • Address: A freeform address to geocode into a latitude and longitude (e.g., 1 Madison Ave, New York, NY 10010 or New York, NY)
Note that providing an address that resolves to an area, like a city or a ZIP code, does not restrict the search to exactly that area; it simply centers the search circle on a point in that area.

To search for a locations with 10 miles of the center point of ZIP code 10010, send the following request:

GEThttps://liveapi.yext.com/v2/accounts/me/locations/geosearch?api_key=[API_KEY]&v=YYYYMMDD&location=10010&radius=10


Response Body:
{
  "meta": {
    "uuid": "aa77933a-18fd-47cd-9159-3b01810a0941",
    "errors": []
  },
  "response": {
    "count": 1,
    "geo": {
      "latitude": 40.7388319,
      "longitude": -73.98153370000001,
      "address": "",
      "address2": "",
      "locality": "New York",
      "region": "NY",
      "postalCode": "10010",
      "country": "US",
      "granularity": "POSTALCODE"
    },
    "locations": [
      {
        "id": "3818285",
        "timestamp": 1494541585402,
        "accountId": "1242569",
        "locationName": "Yext",
        "address": "1 Madison Ave",
        "address2": "5th Floor",
        "city": "New York",
        "state": "NY",
        "zip": "10010",
        "countryCode": "US",
        "language": "en",
        "suppressAddress": false,
        "phone": "8884442988",
        "isPhoneTracked": false,
        "localPhone": "2128136543",
        "categoryIds": [
          "668"
        ],
        "featuredMessage": "Call Today",
        "websiteUrl": "https://locations.yext.com/us/ny/new-york/1-madison-ave.html",
        "description": "Yext is the global location data management leader, and our mission is to help people Go Places™",
        "yextDisplayLat": 40.7411107,
        "yextDisplayLng": -73.987448,
        "yextRoutableLat": 40.741199,
        "yextRoutableLng": -73.98774,
        "folderId": "0",
        "labelIds": [],
        "menusLabel": "",
        "menuIds": [],
        "bioListsLabel": "",
        "bioListIds": [],
        "productListsLabel": "",
        "productListIds": [],
        "eventListsLabel": "",
        "eventListIds": [],
        "locationType": "LOCATION",
        "uberLinkRaw": "https://m.uber.com/ul/?client_id=KXQcwoj2Zb8ymDzKgVgbIaDE5iAE_TAj&action=setPickup&pickup=my_location&dropoff%5Bnickname%5D=Yext&dropoff%5Blatitude%5D=40.741199&dropoff%5Blongitude%5D=-73.98774&dropoff%5Bformatted_address%5D=1%20Madison%20Ave%2C5th%20Floor%2CNew%20York%2CNY",
        "isoRegionCode": "NY"
      }
    ],
    "locationDistances": [
      {
        "id": "3818285",
        "distanceMiles": 0.3471411814527542,
        "distanceKilometers": 0.5586695775239012
      }
    ]
  }
}

NOTE: In the response, we return both a geo object and locationDistances array. The geo object provides information on where the search was centered, and the locationDistances array provides data on the distance of the returned location from the search point.