---
title: "Location-Based Applications Thrive with the Yelp API"
description: "Enhance location-based apps with Yelp API."
canonicalUrl: "https://zuplo.com/learning-center/yelp-api"
pageType: "learning-center"
authors: "nate"
tags: "APIs"
image: "https://zuplo.com/og?text=Location-Based%20Applications%20Thrive%20with%20the%20Yelp%20API"
---
Location-based applications depend on high-quality data to succeed. The
[Yelp API](https://docs.developer.yelp.com/docs/getting-started) provides access
to millions of business listings, reviews, and location data across 32
countries, covering everything from food delivery platforms to travel planners.

This guide covers Yelp API integration from authentication to deployment,
navigating the
[recent shift from free to paid access](https://appdevelopermagazine.com/yelp-fusion-api-outrageous-new-pricing/)
in 2024\. You'll master authentication workflows, endpoint optimization,
performance scaling, and security practices with production-ready code samples.

## **Quick Start: Your First Yelp API Call in 5 Minutes**

Yelp's comprehensive database contains millions of businesses across 32
countries, providing user reviews, ratings, operating hours, photos, and precise
location data. This information forms the backbone of the
[Yelp Fusion API](https://docs.developer.yelp.com/docs/fusion-intro), making it
ideal for location-aware applications that help users discover local businesses
through standardized HTTP requests.

1. **Create a Yelp Account**: Navigate to
   [business.yelp.com/data/products/fusion/](https://business.yelp.com/data/products/fusion/)
   and complete the registration process.
2. **Register Your App**: Once logged in, locate and click the "Get Started"
   button in the [Fusion API](https://docs.developer.yelp.com/docs/fusion-intro)
   section.
3. **Copy Your API Key**: After your application is approved (usually within 1-2
   business days), you'll receive access to your developer dashboard. Navigate
   to the credentials section where you'll find your unique API key.

### Your First API Call

The following example demonstrates how to search for coffee shops near San
Francisco using the Yelp API with cURL. This command sends a GET request to the
business search endpoint with location parameters and your authentication token:

```shell
curl -X GET "https://api.yelp.com/v3/businesses/search?term=coffee&latitude=37.786882&longitude=-122.399972&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

This Node.js example performs the identical search using the axios library to
handle the HTTP request. The code shows proper error handling and parameter
formatting for a production environment:

```javascript
const axios = require("axios");

async function searchYelp() {
  try {
    const response = await axios.get(
      "https://api.yelp.com/v3/businesses/search",
      {
        headers: {
          Authorization: "Bearer YOUR_API_KEY",
        },
        params: {
          term: "coffee",
          latitude: 37.786882,
          longitude: -122.399972,
          limit: 10,
        },
      },
    );

    console.log(response.data.businesses);
  } catch (error) {
    console.error("Error:", error.response?.data || error.message);
  }
}

searchYelp();
```

Replace `YOUR_API_KEY` with your actual key to receive JSON data for coffee
shops in the specified location. The authentication happens through the
`Authorization: Bearer YOUR_API_KEY` header, which is required for all requests
to [Yelp's search endpoint](https://api.yelp.com/v3/businesses/search).

## **What You Get: Yelp's Data Universe & Your Usage Limits**

The [Yelp Fusion API](https://docs.developer.yelp.com/docs/fusion-intro)
provides access to a vast ecosystem of local business data across 32 countries.
Understanding what's available helps you design more effective and engaging user
experiences.

### Three Core Data Objects

**Business Objects** contain essential establishment details including names,
addresses, phone numbers, operating hours, price ranges, and category
classifications. Each business has a unique identifier that enables consistent
data retrieval and relationship mapping between different API calls, ensuring
data integrity throughout your application.

**Review Objects** deliver user-generated content including star ratings,
written feedback, publication dates, and reviewer information. The API
strategically provides review excerpts rather than full content, giving your
users decision-making context without overwhelming them with excessive
information.

**Category Objects** create a taxonomic structure that organizes businesses into
logical groups like "restaurants," "automotive," or "health & medical." This
classification system enables powerful filtering capabilities and helps users
navigate to precisely what they need through intuitive category-based searches.

### Rate Limits You Need to Know

The API employs
[rate limiting](https://docs.developer.yelp.com/docs/fusion-rate-limiting) to
ensure fair usage across all developers. Understanding these constraints is
essential for building applications that
[maintain responsiveness under real-world conditions](/learning-center/api-rate-limiting).
Implement strategic caching, efficient request batching, and intelligent error
handling to maximize your quota utilization while delivering seamless user
experiences.

### JSON Structure

All API responses arrive in standardized JSON format with consistent structure
and predictable field names. This uniformity simplifies integration across
programming languages and frameworks, allowing you to implement streamlined
parsing logic that works reliably across all endpoints.

### Key Endpoints Preview

Your integration will center on several critical endpoints we'll cover in
detail. The
[Business Search endpoint](https://api.yelp.com/v3/businesses/search) handles
location-based queries with powerful filtering options, while Business Details
endpoints provide comprehensive establishment information. Additional
specialized endpoints support phone searches, autocomplete functionality, and
transaction-based filtering for specific use cases.

## **How to Authenticate with the Yelp API: Key vs OAuth Methods**

The Yelp API transitioned to
[API Key authentication](/learning-center/documenting-api-keys) in March 2018,
streamlining the process for most developers. This change simplified
authentication while maintaining security. Partner APIs continue to use OAuth
for specialized use cases where elevated permissions are required.

### API Key Authentication (Fusion API)

Yelp's Fusion API uses
[Bearer token authentication](https://elfsight.com/blog/how-to-get-and-use-yelp-api/)
for accessing business data, search functionality, and reviews. This
straightforward approach requires sending your API key in the Authorization
header with each request, as demonstrated in this example:

```javascript
const response = await fetch("https://api.yelp.com/v3/businesses/search", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  // ... other request parameters
});
```

### OAuth Authentication (Partner APIs)

[Partner APIs](https://docs.developer.yelp.com/docs/partner-apiyelpcom-basic-http-authentication)
require OAuth 2.0 for more privileged operations, such as responding to reviews
on behalf of business owners. The
[OAuth flow](https://docs.developer.yelp.com/docs/oauth-authorization) involves
obtaining an access token through a more complex but more secure process. The
following code shows how to request an access token from the
[token endpoint](https://api.yelp.com/oauth2/token):

```javascript
// OAuth token request to obtain a temporary access token
const tokenResponse = await fetch("https://api.yelp.com/oauth2/token", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: "YOUR_CLIENT_ID",
    client_secret: "YOUR_CLIENT_SECRET",
  }),
});
```

### When to Use Each Method

**API Key for:**

- Consumer applications displaying Yelp business data
- Search interfaces and business discovery features
- Public business information and reviews

**OAuth for:**

- Review management on behalf of business owners
- B2B applications requiring elevated permissions
- Specialized business management features

### Secure Implementation

The following example demonstrates a secure implementation pattern for making
authenticated requests to the Yelp API:

```javascript
require("dotenv").config();

const yelpConfig = {
  apiKey: process.env.YELP_API_KEY,
  baseUrl: "https://api.yelp.com/v3",
};

async function searchBusinesses(term, location) {
  try {
    const response = await fetch(`${yelpConfig.baseUrl}/businesses/search`, {
      headers: {
        Authorization: `Bearer ${yelpConfig.apiKey}`,
      },
    });
    return await response.json();
  } catch (error) {
    console.error("Authentication failed:", error);
    throw error;
  }
}
```

## **Master These Core Yelp API Endpoints & Sample Queries**

The [Yelp Fusion API](https://docs.developer.yelp.com/docs/fusion-intro)
provides several essential endpoints that power location-based applications.
Understanding these core endpoints will enable you to build comprehensive
business discovery features in your applications.

### **Business Search Endpoint**

The `/businesses/search` endpoint is your primary tool for discovering
businesses based on location and search criteria. This foundational endpoint
will typically serve as the entry point for users in your application.

| Parameter    | Type   | Required | Description                                 |
| ------------ | ------ | -------- | ------------------------------------------- |
| `term`       | string | No       | Search term (e.g., "pizza", "restaurants")  |
| `location`   | string | Yes\*    | Location string (e.g., "San Francisco, CA") |
| `latitude`   | float  | Yes\*    | Latitude coordinate                         |
| `longitude`  | float  | Yes\*    | Longitude coordinate                        |
| `radius`     | int    | No       | Search radius in meters (max 40,000)        |
| `categories` | string | No       | Comma-delimited category filters            |
| `limit`      | int    | No       | Number of results (max 50, default 20\)     |
| `offset`     | int    | No       | Result offset for pagination                |

\*Either `location` OR `latitude`/`longitude` is required.

The following code sample demonstrates how to perform a basic business search
query, process the response, and extract the most relevant business information.
This pattern forms the foundation of most Yelp-powered search features:

```javascript
const axios = require("axios");

async function searchBusinesses(term, location) {
  try {
    const response = await axios.get(
      "https://api.yelp.com/v3/businesses/search",
      {
        headers: {
          Authorization: `Bearer ${process.env.YELP_API_KEY}`,
        },
        params: {
          term: term,
          location: location,
          limit: 20,
          sort_by: "best_match",
        },
      },
    );

    return response.data.businesses.map((business) => ({
      id: business.id,
      name: business.name,
      rating: business.rating,
      price: business.price,
      coordinates: business.coordinates,
      categories: business.categories.map((cat) => cat.title),
    }));
  } catch (error) {
    console.error("Search error:", error.response?.data);
    throw error;
  }
}
```

### **Business Details Endpoint**

Once users select a business from search results, you'll need detailed
information about that specific establishment. The `/businesses/{id}` endpoint
retrieves comprehensive business data using the unique Yelp ID obtained from
your initial search.

The code below shows how to fetch and structure detailed business information,
including hours, location, photos, and other attributes that enhance your
application's user experience:

```javascript
async function getBusinessDetails(businessId) {
  try {
    const response = await axios.get(
      `https://api.yelp.com/v3/businesses/${businessId}`,
      {
        headers: {
          Authorization: `Bearer ${process.env.YELP_API_KEY}`,
        },
      },
    );

    const business = response.data;
    return {
      name: business.name,
      rating: business.rating,
      reviewCount: business.review_count,
      phone: business.phone,
      hours: business.hours,
      address: business.location.display_address.join(", "),
      photos: business.photos,
      attributes: business.attributes,
    };
  } catch (error) {
    console.error("Business details error:", error.response?.data);
    throw error;
  }
}
```

### **Reviews Endpoint**

To provide social proof and user sentiment about businesses, you'll want to
display reviews. The `/businesses/{id}/reviews` endpoint delivers up to three
review excerpts for any given business, helping users make informed decisions
based on others' experiences.

This example demonstrates how to fetch and format review data, including user
information and ratings, which can significantly influence user decisions:

```javascript
async function getBusinessReviews(businessId) {
  try {
    const response = await axios.get(
      `https://api.yelp.com/v3/businesses/${businessId}/reviews`,
      {
        headers: {
          Authorization: `Bearer ${process.env.YELP_API_KEY}`,
        },
      },
    );

    return response.data.reviews.map((review) => ({
      rating: review.rating,
      text: review.text,
      timeCreated: review.time_created,
      user: {
        name: review.user.name,
        imageUrl: review.user.image_url,
      },
    }));
  } catch (error) {
    console.error("Reviews error:", error.response?.data);
    throw error;
  }
}
```

### **Additional Endpoints**

**Autocomplete Endpoint** (`/autocomplete`) enhances user experience by
providing real-time search suggestions as users type. This implementation shows
how to integrate type-ahead functionality that helps users find what they're
looking for more quickly:

```javascript
async function getAutocomplete(text, latitude, longitude) {
  const response = await axios.get("https://api.yelp.com/v3/autocomplete", {
    headers: { Authorization: `Bearer ${process.env.YELP_API_KEY}` },
    params: { text, latitude, longitude },
  });
  return response.data.terms.map((term) => term.text);
}
```

**Phone Search Endpoint** (`/businesses/search/phone`) offers a specialized
search capability for finding businesses by their phone number. This is
particularly useful for verification purposes or when matching existing business
data with Yelp's database:

```javascript
async function searchByPhone(phoneNumber) {
  const response = await axios.get(
    "https://api.yelp.com/v3/businesses/search/phone",
    {
      headers: { Authorization: `Bearer ${process.env.YELP_API_KEY}` },
      params: { phone: phoneNumber },
    },
  );
  return response.data.businesses;
}
```

### **Location Parameter Trade-offs**

When implementing location-based search, you must choose between location
strings and coordinates. Each approach offers distinct advantages depending on
your application's context:

**Location Strings** (e.g., "Seattle, WA"):

- **User Experience**: Provides a natural interface for users who think in terms
  of city names or addresses rather than coordinates
- **Server-Side Simplicity**: Eliminates the need for client-side geocoding, as
  Yelp handles the conversion to coordinates
- **Fuzzy Matching**: Accommodates misspellings and partial location names,
  improving user success rates
- **Regional Awareness**: Often returns results that consider administrative
  boundaries, which can be beneficial for certain searches

**Latitude/Longitude Coordinates**:

- **Precision**: Enables pinpoint accuracy for location-based searches, critical
  for "near me" functionality
- **Consistency**: Delivers more predictable results by eliminating location
  name ambiguity (e.g., "Springfield" exists in multiple states)
- **Mobile Integration**: Seamlessly incorporates with device GPS capabilities
  for real-time location searches
- **Performance**: Often provides faster results as it bypasses Yelp's geocoding
  process

For mobile applications, coordinates typically offer better performance and
accuracy, particularly when users are on the move. Web applications may benefit
from location strings for their user-friendly nature and broader search context.
Consider implementing both options to accommodate different user scenarios and
preferences.

### **Response Parsing Best Practices**

When working with external APIs like Yelp, response data quality and structure
can vary significantly between requests. Implement defensive programming
techniques when parsing these responses to prevent your application from
crashing due to missing fields, null values, or unexpected data formats. The
following code example demonstrates a robust parsing function that handles
potential inconsistencies in Yelp business data:

```javascript
function parseBusinessSafely(business) {
  return {
    id: business.id || "",
    name: business.name || "Unknown Business",
    rating: business.rating || 0,
    price: business.price || "Not specified",
    phone: business.display_phone || business.phone || "",
    address:
      business.location?.display_address?.join(", ") || "Address unavailable",
    categories: business.categories?.map((cat) => cat.title) || [],
    imageUrl: business.image_url || "",
    isClosed: business.is_closed || false,
  };
}
```

This defensive approach provides several key benefits for your application:

1. Crash prevention: The function gracefully handles missing properties by
   providing sensible defaults
2. Improved user experience: Even with incomplete API data, users still see
   meaningful information
3. Simplified debugging: Clear fallback values make it easier to identify which
   fields were missing in the original response
4. Consistent data structure: Downstream components can rely on a predictable
   object format regardless of API response variations

By implementing similar parsing patterns throughout your application, you'll
create a more resilient system that can withstand the inconsistencies often
encountered when working with third-party APIs.

## **How to Build Complex Yelp API Searches That Scale**

The Yelp API caps individual requests at 50 results and total results at 1,000
per search. The search endpoint returns a
[maximum of 20 businesses by default](https://github.com/Yelp/yelp-fusion/issues/117),
making effective pagination crucial for comprehensive data collection. Let's
explore strategies to maximize your data retrieval while respecting API
limitations.

### **Pagination That Respects API Limits**

The following implementation demonstrates a robust pagination approach that
handles Yelp's constraints. This function makes multiple requests with
increasing offsets, incorporates error handling, and adds a small delay between
requests to avoid rate limiting issues:

```javascript
async function getAllBusinesses(searchParams, maxResults = 200) {
  const businesses = [];
  const limit = 50; // Maximum allowed per request
  let offset = 0;

  while (businesses.length < maxResults && offset < 1000) {
    try {
      const response = await fetch(
        `https://api.yelp.com/v3/businesses/search?${new URLSearchParams({
          ...searchParams,
          limit,
          offset,
        })}`,
        {
          headers: {
            Authorization: `Bearer ${process.env.YELP_API_KEY}`,
          },
        },
      );

      const data = await response.json();

      if (data.businesses?.length > 0) {
        businesses.push(...data.businesses);
        offset += limit;
        await new Promise((resolve) => setTimeout(resolve, 100)); // Throttle requests
      } else {
        break; // No more results available
      }
    } catch (error) {
      console.error("Pagination error:", error);
      break;
    }
  }

  return businesses.slice(0, maxResults);
}
```

### **Powerful Filter Combinations**

Yelp's API offers versatile filtering capabilities that can be combined for
precise targeting. Here are some effective combinations that address common
search scenarios:

**Category and Price Filtering**

This example shows how to target specific business types within budget
constraints, perfect for apps that help users find affordable dining options:

```javascript
const restaurantSearch = {
  location: "San Francisco, CA",
  categories: "restaurants,bars",
  price: "1,2,3", // $ to $$$ price ranges
  open_now: true,
  sort_by: "rating",
};
```

**Attribute-Based Targeting**

When accessibility and amenities matter to your users, this filtering approach
helps find businesses with specific features. This is especially valuable for
users with special requirements:

```javascript
const accessibleRestaurants = {
  location: "Seattle, WA",
  term: "dinner",
  attributes: "wheelchair_accessible,outdoor_seating,wifi",
  radius: 5000, // 5km radius
  limit: 20,
};
```

**Time-Based Filtering**

For applications that need to show availability based on specific times, this
combination ensures results are relevant to the user's immediate needs:

```javascript
const openNowSearch = {
  location: "Austin, TX",
  categories: "coffee",
  open_now: true,
  open_at: Math.floor(Date.now() / 1000), // Current Unix timestamp
};
```

### **Smart Caching Implementation**

[Yelp allows caching API responses for up to 24 hours](https://docs.developer.yelp.com/docs/fusion-rate-limiting),
which is essential for managing rate limits and improving application
performance. This implementation creates a reusable cache system that respects
Yelp's guidelines. For more on
[caching API responses](/blog/cachin-your-ai-responses), this guide provides
practical examples:

```javascript
class YelpSearchCache {
  constructor() {
    this.cache = new Map();
    this.cacheTimeout = 24 * 60 * 60 * 1000; // 24 hours in milliseconds
  }

  getCacheKey(params) {
    return JSON.stringify(params, Object.keys(params).sort());
  }

  async searchWithCache(params) {
    const cacheKey = this.getCacheKey(params);
    const cached = this.cache.get(cacheKey);

    if (cached && Date.now() - cached.timestamp < this.cacheTimeout) {
      return cached.data; // Return cached data if valid
    }

    const response = await this.makeYelpRequest(params);

    this.cache.set(cacheKey, {
      data: response,
      timestamp: Date.now(),
    });

    return response;
  }

  async makeYelpRequest(params) {
    const url = `https://api.yelp.com/v3/businesses/search?${new URLSearchParams(params)}`;
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.YELP_API_KEY}` },
    });

    if (!response.ok) {
      throw new Error(`Yelp API error: ${response.status}`);
    }

    return response.json();
  }
}
```

### **Geographic Precision Options**

Location-based searches are at the heart of Yelp's functionality. Depending on
your use case, you can choose between different location targeting approaches:

**Coordinate-Based (Most Precise)**

When you have exact user coordinates (such as from GPS), this approach provides
the most accurate results for proximity-based searches:

```javascript
const preciseSearch = {
  latitude: 40.7589,
  longitude: -73.9851, // Times Square, NYC coordinates
  radius: 1000, // 1km search radius
  term: "pizza",
};
```

**Localized Results**

For international applications or when targeting specific linguistic regions,
this approach ensures culturally relevant results with proper localization:

```javascript
const localizedSearch = {
  location: "Paris, France",
  term: "restaurant",
  locale: "fr_FR", // French locale for proper sorting and relevance
  categories: "french",
};
```

### **Production-Ready Query Combination**

The following example demonstrates a comprehensive search implementation for a
food delivery application. It combines multiple filtering techniques, implements
pagination, incorporates caching, and includes post-processing of results:

```javascript
async function findDeliveryRestaurants(
  userLocation,
  cuisinePreferences,
  priceRange,
) {
  const searchParams = {
    latitude: userLocation.lat,
    longitude: userLocation.lng,
    categories: cuisinePreferences.join(","),
    price: priceRange.join(","),
    attributes: "delivery,takeout",
    sort_by: "distance",
    radius: 8000, // 8km radius
    limit: 50,
    open_now: true,
  };

  const allResults = [];
  let offset = 0;
  const maxPages = 4; // Limit to 200 total results

  for (let page = 0; page < maxPages; page++) {
    const pagedParams = { ...searchParams, offset };

    try {
      const results = await yelpCache.searchWithCache(pagedParams);

      if (results.businesses?.length > 0) {
        allResults.push(...results.businesses);
        offset += searchParams.limit;

        if (results.businesses.length < searchParams.limit) {
          break; // End of available results
        }
      } else {
        break;
      }
    } catch (error) {
      console.error("Search failed for page", page, error);
      break;
    }
  }

  // Post-process results for quality and relevance
  return allResults
    .filter((business) => business.rating >= 3.5)
    .sort((a, b) => b.rating - a.rating)
    .slice(0, 20);
}
```

### **Batch Processing with Rate Limit Handling**

When collecting data at scale from the Yelp API, proper rate limit handling
becomes essential to avoid request throttling or IP banning. The following code
demonstrates an efficient batch processing implementation that respects
[rate limit considerations](https://docs.developer.yelp.com/docs/fusion-rate-limiting)
while providing resilience through exponential backoff retry logic.

```javascript
async function batchCollectBusinessData(locations, options = {}) {
  const { batchSize = 5, delayBetweenBatches = 1000, maxRetries = 3 } = options;

  const results = [];

  for (let i = 0; i < locations.length; i += batchSize) {
    const batch = locations.slice(i, i + batchSize);

    const batchPromises = batch.map(async (location, index) => {
      // Stagger requests within batch to avoid API rate limits
      await new Promise((resolve) => setTimeout(resolve, index * 200));

      return retryWithBackoff(async () => {
        return await searchWithPagination({
          location: location.name,
          categories: location.categories,
          limit: 50,
        });
      }, maxRetries);
    });

    try {
      const batchResults = await Promise.all(batchPromises);
      results.push(...batchResults.flat());

      // Pause between batches to respect API rate limits
      if (i + batchSize < locations.length) {
        await new Promise((resolve) =>
          setTimeout(resolve, delayBetweenBatches),
        );
      }
    } catch (error) {
      console.error(`Batch ${Math.floor(i / batchSize)} failed:`, error);
    }
  }

  return results;
}

// Implements exponential backoff strategy for failed requests
async function retryWithBackoff(fn, maxRetries) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;

      const backoffTime = Math.pow(2, attempt) * 1000;
      await new Promise((resolve) => setTimeout(resolve, backoffTime));
    }
  }
}
```

This approach balances throughput with API compliance by implementing three key
strategies: request batching to process multiple locations simultaneously,
staggered requests within batches to prevent instantaneous traffic spikes, and
exponential backoff for automatic recovery from temporary failures. By
intelligently managing your API consumption patterns, you can build robust
applications that efficiently collect comprehensive business data while
maintaining good standing with the API provider.

For more insights on implementing
[rate limiting in NodeJS](https://zuplo.com/learn/how-to-rate-limit-apis-nodejs),
refer to our comprehensive tutorial.

## **How to Scale Your Yelp API Integration for High Performance**

Building applications that rely heavily on the Yelp API means tackling
performance and scalability challenges head-on. The real test comes when you
need to handle
[rate limits effectively while maintaining low latency](https://docs.developer.yelp.com/docs/fusion-rate-limiting)
across multiple geographic regions. For general strategies on
[improving API performance](/learning-center/increase-api-performance), our
guide offers valuable insights.

API management platforms like Zuplo solve this with a code-first approach that
fits your existing developer workflow. Define your API gateway policies directly
in TypeScript instead of wrestling with complex configuration interfaces. You
can version control, test, and deploy your integration logic alongside your
application code.

Edge execution capabilities spanning hundreds of data centers globally reduce
latency between your application and the Yelp API. This matters most for
real-time features like location-based search, where every millisecond affects
user experience.

Here's how to implement intelligent request routing and caching with TypeScript:

```ts
import { ZuploRequest, ZuploContext } from "@zuplo/runtime";

export default async function yelpProxyHandler(
  request: ZuploRequest,
  context: ZuploContext,
) {
  const cacheKey = `yelp:${request.url}`;

  // Check edge cache first
  const cached = await context.cache.get(cacheKey);
  if (cached) {
    return new Response(cached, {
      headers: { "Content-Type": "application/json" },
    });
  }

  // Forward to Yelp API with proper headers
  const yelpResponse = await fetch(
    request.url.replace("/api/yelp", "https://api.yelp.com/v3"),
    {
      headers: {
        Authorization: `Bearer ${context.env.YELP_API_KEY}`,
        Accept: "application/json",
      },
    },
  );

  const data = await yelpResponse.text();

  // Cache successful responses for 1 hour
  if (yelpResponse.ok) {
    await context.cache.put(cacheKey, data, { expirationTtl: 3600 });
  }

  return new Response(data, {
    status: yelpResponse.status,
    headers: { "Content-Type": "application/json" },
  });
}
```

### **Handling Yelp API Rate-Limits Gracefully**

Rate limiting creates the biggest bottleneck when scaling Yelp API usage. The
[Fusion API enforces strict limits](https://docs.developer.yelp.com/docs/fusion-rate-limiting)
that quickly become problems as your application grows. Smart rate limiting
policies improve your application's reliability and cost efficiency.

You can implement intelligent rate limiting policies that adapt to Yelp's
constraints while providing optimal performance. For more advanced
[API rate limiting techniques](/learning-center/subtle-art-of-rate-limiting-an-api),
consider exploring our in-depth article:

```ts
import { ZuploRequest, ZuploContext } from "@zuplo/runtime";

interface RateLimitState {
  requests: number;
  resetTime: number;
}

export default async function rateLimitHandler(
  request: ZuploRequest,
  context: ZuploContext,
) {
  const clientId = request.headers.get("x-client-id") || "anonymous";
  const rateLimitKey = `rate_limit:${clientId}`;

  // Get current rate limit state
  const currentState: RateLimitState = (await context.cache.get(
    rateLimitKey,
  )) || {
    requests: 0,
    resetTime: Date.now() + 60000, // 1 minute window
  };

  // Reset counter if window expired
  if (Date.now() > currentState.resetTime) {
    currentState.requests = 0;
    currentState.resetTime = Date.now() + 60000;
  }

  // Check if limit exceeded (50 requests per minute)
  if (currentState.requests >= 50) {
    return new Response(
      JSON.stringify({
        error: "Rate limit exceeded",
        retryAfter: Math.ceil((currentState.resetTime - Date.now()) / 1000),
      }),
      {
        status: 429,
        headers: {
          "Content-Type": "application/json",
          "Retry-After": Math.ceil(
            (currentState.resetTime - Date.now()) / 1000,
          ).toString(),
        },
      },
    );
  }

  // Increment counter and update cache
  currentState.requests++;
  await context.cache.put(rateLimitKey, currentState, {
    expirationTtl: Math.ceil((currentState.resetTime - Date.now()) / 1000),
  });

  return undefined; // Continue to next handler
}
```

This approach delivers three performance benefits that directly impact your
application. **Lower latency** through edge caching and intelligent routing
reduces response times by up to 80%. **Fewer 429 errors** through proactive rate
limiting prevents cascading failures during traffic spikes. **Cost savings**
through efficient request management can reduce your API usage by 60% or more,
as demonstrated in
[real-world implementations](https://letstalkdata.com/2014/02/how-to-use-the-yelp-api-in-python/)
where caching strategies significantly reduced redundant API calls.

The difference becomes clear when comparing error rates and response times under
load. Without proper rate limiting, applications experience request failures and
degraded performance during peak usage. A well-designed gateway maintains
consistent performance regardless of traffic patterns.

## **Fix Common Yelp API Errors in Minutes**

When building with the Yelp API, proper error handling separates
production-ready applications from brittle prototypes.
[Common error responses](https://docs.developer.yelp.com/docs/api-errors) follow
predictable patterns—understanding them saves hours of debugging.

**Status Codes That Matter**

The Yelp API uses standard HTTP status codes that indicate specific issues with
your requests:

- **400 Bad Request**: Occurs when you've provided invalid parameters or
  malformed requests. This might happen when using incorrect location formats,
  invalid sort options, or missing required parameters like location or term in
  search requests.
- **401 Unauthorized**: Indicates authentication failures, typically caused by
  invalid API keys, expired tokens, or improper key formatting in your
  Authorization header. Always verify your API key is current and properly
  formatted with the "Bearer" prefix.
- **429 Too Many Requests**: You've hit Yelp's
  [rate limit](https://docs.developer.yelp.com/docs/fusion-rate-limiting), which
  restricts accounts to 500 requests per day and 5,000 per month. Implement
  proper request throttling and caching strategies to avoid this limitation.
- **500 Internal Server Error**: Represents temporary server-side issues within
  Yelp's infrastructure. These errors are typically transient and require a
  strategic retry approach rather than code changes on your end.

**Implementing Robust Error Handling**

The following code demonstrates a bulletproof pattern for handling Yelp API
errors in JavaScript. This implementation captures all common error scenarios
and provides appropriate responses for each:

```javascript
async function callYelpAPI(endpoint, params) {
  try {
    const response = await fetch(`https://api.yelp.com/v3/${endpoint}`, {
      headers: { Authorization: `Bearer ${process.env.YELP_API_KEY}` },
      params,
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new YelpAPIError(response.status, errorData);
    }

    return await response.json();
  } catch (error) {
    return handleYelpError(error);
  }
}

function handleYelpError(error) {
  switch (error.status) {
    case 401:
      console.error("Authentication failed - check your API key");
      return { error: "Invalid credentials" };
    case 429:
      console.error("Rate limit exceeded - implementing backoff");
      return scheduleRetryWithBackoff(error);
    case 400:
      console.error("Invalid request parameters:", error.message);
      return { error: "Invalid search parameters" };
    default:
      console.error("Unexpected error:", error);
      return { error: "Service temporarily unavailable" };
  }
}
```

**Quick Resolution Path**

1. **401 Error?** → Verify your API key format including the "Bearer" prefix and
   check for expiration. Ensure your key is stored securely in environment
   variables and not exposed in client-side code. Consider rotating your key if
   you suspect it's been compromised.
2. **429 Error?** → Implement exponential backoff with increasing delay
   intervals between retries. Review your request frequency patterns and
   consider implementing a queue system. Leverage local caching for frequently
   accessed data, as Yelp permits 24-hour caching of business information.
3. **400 Error?** → Carefully validate all search parameters before sending.
   Ensure location parameters follow Yelp's expected format (city/state or
   latitude/longitude pairs). Check that categories match Yelp's official
   category list and that radius values stay within permitted limits.
4. **Business not found?** → Confirm the business ID validity and check if the
   business still exists using a manual search on yelp.com. Business IDs might
   change if a business relocates or changes ownership, so implement a fallback
   search strategy for critical applications.

**Production-Grade Monitoring with Zuplo**

Zuplo's API management platform streams detailed logs to Datadog, giving you
real-time visibility into API performance metrics, error patterns, and request
flows. This integration catches issues before they impact users by providing
actionable insights into rate limiting approaches, error frequency, and response
time anomalies.

**The Big Three Troubleshooting Issues**

Authentication problems are the most common errors—never hardcode API keys in
client-side code. Use environment variables and server-side proxies to protect
your credentials. Rate limiting typically impacts production apps as they scale;
implement strategic caching for business data and throttle requests during peak
usage periods. Parameter validation errors often result from incorrect location
formats or invalid business IDs, which can be mitigated with input validation
libraries.

For persistent issues, check the
[Yelp Fusion FAQ](https://docs.developer.yelp.com/docs/fusion-faq) or contact
api@yelp.com with specific error details and request examples. Ready to take
your API error handling to the next level? Try Zuplo today for advanced
monitoring, rate limiting controls, and seamless integration with your existing
API infrastructure.

## **How to Monitor Your Yelp API Integration Like a Pro**

Your Yelp API integration will fail without proper monitoring. Track these
critical metrics to prevent downtime and optimize performance. Utilizing
[API monitoring tools](/learning-center/8-api-monitoring-tools-every-developer-should-know)
can help you stay ahead of potential issues.

**Essential Metrics That Matter**

Monitor these three metrics to maintain reliable service:

- **Call Volume**: Track requests per hour to predict when you'll hit
  [rate limits](https://docs.developer.yelp.com/docs/fusion-rate-limiting)
- **P95 Latency**: Monitor 95th percentile response times to catch performance
  issues early
- **Error Rates**: Track 4xx/5xx responses to identify integration problems fast

**Basic Monitoring Setup**

Here's a Node.js implementation for tracking these metrics:

```javascript
class YelpAPIMonitor {
  constructor() {
    this.metrics = {
      totalCalls: 0,
      errorCounts: { "4xx": 0, "5xx": 0 },
      responseTimes: [],
    };
  }

  async monitoredRequest(apiCall) {
    const startTime = Date.now();

    try {
      const response = await apiCall();
      this.recordSuccess(Date.now() - startTime);
      return response;
    } catch (error) {
      this.recordError(error.response?.status, Date.now() - startTime);
      throw error;
    }
  }

  recordSuccess(responseTime) {
    this.metrics.totalCalls++;
    this.metrics.responseTimes.push(responseTime);
  }

  recordError(statusCode, responseTime) {
    this.metrics.totalCalls++;
    if (statusCode >= 400 && statusCode < 500) {
      this.metrics.errorCounts["4xx"]++;
    } else if (statusCode >= 500) {
      this.metrics.errorCounts["5xx"]++;
    }
  }
}
```

**Smart Alerting That Prevents Outages**

Set up proactive notifications before problems hit your users:

```javascript
function checkAndAlert() {
  const dailyUsage = getCurrentDayUsage();
  const threshold = getDailyLimit() * 0.8; // Alert at 80% usage

  if (dailyUsage > threshold) {
    sendSlackAlert(
      `⚠️ Yelp API usage at ${dailyUsage} calls (${threshold} threshold exceeded)`,
    );
  }
}
```

**Grafana Dashboard Setup**

Create dashboards that surface problems before they escalate. Your Grafana setup
should track:

- API call volume trends with clear spike detection
- Error rate percentages by endpoint with automated threshold alerts
- Response time percentiles with SLA breach notifications

This visual approach turns raw metrics into actionable insights that keep your
integration stable.

**Zuplo's Global Monitoring Edge**

Zuplo's monitoring capabilities provide edge-level metrics across 300+ data
centers, giving you granular visibility into API performance globally. This
distributed approach helps identify regional performance issues and optimize
your API gateway configuration.
[Rate limiting best practices](https://stytch.com/learning-center/api-rate-limiting)
become easier to implement when you can see performance patterns across
different geographic regions in real-time.

## **Compare Features Across Yelp's Pricing Tiers**

Yelp transitioned from free to
[paid-only access](https://appdevelopermagazine.com/yelp-fusion-api-outrageous-new-pricing/)
in 2024, reshaping how developers budget for business data. Understanding each
tier's capabilities helps you select the right plan before hitting usage limits.

### **Trial Tier**

The [30-day free trial](https://business.yelp.com/data/products/fusion/)
provides complete API access with volume restrictions, offering full business
search functionality and review excerpts—ideal for prototyping without upfront
costs while establishing baseline usage metrics.

### **Volume-Based Paid Plans**

Yelp structures pricing around
[1,000 API calls as the billing unit](https://business.yelp.com/data/products/fusion/)
across three monthly tiers:

**Starter Plan**  
Entry-level option for modest usage requirements, providing cost efficiency for
smaller applications while maintaining access to all Fusion API endpoints.

**Professional Plan**  
Mid-tier solution for growing applications with moderate traffic, featuring
increased call allowances for established projects beyond the prototype phase.

**Enterprise Plan**  
Premium tier designed for large-scale applications requiring substantial API
access, including the most generous limits and enhanced support for
mission-critical integrations.

### **Rate Limiting by Tier**

Your pricing tier directly determines your
[rate limiting thresholds](https://docs.developer.yelp.com/docs/fusion-rate-limiting)
across multiple dimensions:

- **Queries per second (QPS)**: Starter plans typically allow 3-5 QPS,
  Professional plans offer 8-10 QPS, while Enterprise tiers support 15+ QPS for
  high-volume applications
- **Concurrent request limits**: Range from 5 simultaneous connections on
  Starter plans to 25+ on Enterprise tiers, directly impacting parallel
  processing capabilities
- **Daily volume caps**: Starter plans include 100K-250K daily calls,
  Professional plans offer 500K-1M, and Enterprise plans provide 2M+ daily
  request allowances
- **Burst capacity**: Enterprise tiers include 2-3x normal capacity for handling
  traffic spikes, while lower tiers offer limited or no burst allowance for
  unexpected demand surges

These parameters determine how effectively your application handles peak traffic
without encountering throttling issues that could impact user experience.

### **Selecting Your Tier**

Consider your application's growth trajectory and user engagement patterns when
choosing tiers. Effective caching reduces redundant API calls, potentially
allowing operation on lower tiers, while real-time applications requiring
frequent data refreshes need higher tiers.

The
[transition to paid access](https://techcrunch.com/2024/08/02/yelps-lack-of-transparency-around-api-charges-angers-developers/)
has prompted developers to reassess integration strategies. Start with the trial
tier to establish baseline metrics, then select a paid tier that provides
adequate headroom for expected growth while maintaining cost efficiency.

## **Exploring Alternatives**

Yelp's
[abrupt transition to paid-only API access](https://techcrunch.com/2024/08/02/yelps-lack-of-transparency-around-api-charges-angers-developers/)
caught many developers off guard, forcing rapid migrations from applications
that relied on years of free access. Similar
[API pricing controversies](/learning-center/reddit-api-guide) have occurred
with other platforms as well. Here are effective replacements to consider:

### **Google Places API**

Google Places offers the most direct Yelp replacement with superior global
coverage—spanning 200+ countries versus Yelp's 32\. The integration with Google
Maps provides richer location context through advanced geospatial features like
polygon search and nearby place detection.

**Best for**: International applications, map-heavy interfaces, comprehensive
business data  
**Watch out for**: Pricing scales quickly with volume, less community-driven
review culture than Yelp

### **Foursquare Places API**

Foursquare excels at personalization and location intelligence. Their API
emphasizes user behavior patterns over raw reviews, providing contextual
recommendations based on historical visit patterns and demographic similarities
that Yelp can't match.

**Best for**: Personalized recommendation engines, urban-focused applications,
behavioral analytics  
**Watch out for**: Weaker review content, requires significant code
restructuring from Yelp

### **TripAdvisor Content API**

TripAdvisor dominates travel and hospitality verticals with detailed restaurant
and attraction reviews. Their content includes authentic traveler photos,
detailed amenity information, and granular ratings breakdowns that provide
deeper insights for hospitality applications.

**Best for**: Restaurant discovery, travel planning, hospitality applications  
**Watch out for**: Limited general business coverage, partnership application
required

### **Multi-Source Strategy**

Smart developers are combining multiple data sources rather than swapping one
dependency for another. This approach creates resilience through data
triangulation—when one source has gaps, others fill in, resulting in more
complete business profiles.

### **OpenStreetMap for Cost Control**

OpenStreetMap delivers comprehensive location data without usage fees or vendor
lock-in. While it lacks review functionality, OSM's community-maintained
database often contains unique local insights missing from commercial providers,
especially in regions with active contributor communities.

**Best for**: Cost-sensitive projects, global coverage needs, applications
requiring extensive customization  
**Watch out for**: No review data, inconsistent quality across regions, requires
additional development

## **Building With the Yelp API at Scale**

If you're building at enterprise scale,
[API management solutions](https://zuplo.com/?utm_source=blog) like Zuplo
provide global edge execution and monitoring that works specifically well with
location-based APIs like Yelp's.

Ready to take your API management to the next level?
[Book a demo](https://zuplo.com/meeting?utm_source=blog) today to discover how
Zuplo can streamline your integration workflow, enhance security, and
drastically reduce your development time with powerful APIs like Yelp, Apple
Music, and more\!