Barglance Partner API Reference

Version: 1.0
Base URL: https://partner-api.barglance.com

Introduction

The Barglance Partner API provides programmatic access to our comprehensive database of bars, events, and social content. Built for data partners, analytics platforms, and integration partners who need reliable access to real-time bar data.

Use Cases:

• Build bar discovery applications
• Aggregate nightlife data across cities
• Power recommendation engines
• Create analytics dashboards
• Integrate bar data into existing platforms

Data Included:

• Bar profiles (name, address, hours, categories)
• Real-time occupancy data
• Events and specials
• Photos and media
• User-generated content (posts)
• Location data

Getting Started

1. Get API Credentials

Contact Barglance to receive:

• Subscriber ID
• API Key token
• Plan assignment

2. Make Your First Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://partner-api.barglance.com/api/v1/partner/test_endpoint

3. Explore the Endpoints

Start with the List Bars endpoint to browse available data, then use Get Bar Details for comprehensive information about specific venues.

Authentication

All API requests require authentication via API key.

Methods

Preferred: Bearer token in Authorization header

Authorization: Bearer YOUR_API_KEY

Alternative: Custom header

X-API-Key: YOUR_API_KEY

Authentication Errors

Rate Limiting

Rate limits are enforced per API key based on your subscription plan.

Limits by Plan

Rate Limit Headers

Every response includes headers to track your usage:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1700000000

X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 45
X-RateLimit-Reset-Minute: 1700000000

X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 856
X-RateLimit-Reset-Day: 1700086400

X-RateLimit-Limit-Month: 10000
X-RateLimit-Remaining-Month: 7234
X-RateLimit-Reset-Month: 1702598400

Rate Limit Exceeded

When you exceed a limit, you'll receive:

Response: 429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "limit": 60,
  "period": "minute"
}

Headers:

Retry-After: 42

The Retry-After header tells you how many seconds to wait before retrying.

Usage Alerts

The API automatically tracks when your usage approaches limits and creates alerts at:

• 80% - Warning
• 90% - High warning
• 100% - Limit reached

Alerts are logged and can be viewed via the admin API (contact Barglance for access).

Note: Currently, alerts are only logged and require manual checking via the admin API. You will not receive proactive notifications at this time.

Future: Email notifications will be added to proactively notify you when approaching limits.

---

Error Handling

Standard Error Response

{
  "error": "Error message description"
}

Common HTTP Status Codes

Error Handling Best Practices

1. Check status codes before parsing response
2. Implement exponential backoff for 429 errors
3. Log errors with request IDs for debugging
4. Handle network errors gracefully
5. Monitor rate limit headers proactively

Example Error Handling:

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  await sleep(retryAfter * 1000);
  return retry(request);
}

---

Best Practices

1. Respect Rate Limits

• Monitor X-RateLimit-Remaining headers
• Implement request throttling
• Use exponential backoff when approaching limits
• Cache responses when appropriate

2. Optimize Requests

• Use specific filters to reduce payload size
• Request only the data you need
• Implement pagination for large datasets
• Batch requests when possible (use ids parameter)

3. Handle Errors Gracefully

• Implement retry logic with exponential backoff
• Log errors with context for debugging
• Have fallback strategies for critical data
• Monitor API health and your usage patterns

4. Security

• Never expose API keys in client-side code
• Rotate keys periodically
• Use HTTPS for all requests
• Store keys securely (environment variables, secrets manager)

5. Performance

• Cache responses when data doesn't change frequently
• Use CDN for static assets (photos, images)
• Implement request queuing to avoid rate limits
• Monitor your API usage and optimize accordingly

6. Data Freshness

• Occupancy data updates in real-time
• Events data should be refreshed daily
• Bar profile data changes infrequently (cache longer)

---

Changelog

Version 1.0 (Current)

• Initial release
• 8 endpoints: test, bars list/show, city bars, city events, city posts, city feed, search
• Rate limiting with minute/day/month buckets
• Usage alerts at 80%, 90%, 100% thresholds
• Comprehensive error handling

Upcoming

• Email notifications for usage alerts
• Webhook support for real-time updates
• GraphQL endpoint (beta)
• Additional filtering options
• Bulk export capabilities

---

Support

Questions? Contact your Barglance partner representative or email [email protected]

Found a bug? Report issues to [email protected] with:

• Request ID (from error response)
• Timestamp
• Request details (endpoint, parameters)
• Expected vs actual behavior