Partner API Endpoints

Endpoints

Test Endpoint

Verify API connectivity and authentication.

Endpoint: GET /api/v1/partner/test_endpoint

Parameters: None

Example Request:

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

Example Response:

{
  "message": "Partner API is working!",
  "timestamp": "2025-01-15T10:30:00Z",
  "subscriber_id": "abc123",
  "plan": "standard"
}

List Bars

Retrieve a list of bars with optional filtering.

Endpoint: GET /api/v1/partner/bars

Query Parameters

Parameter	Type	Required	Default	Description
`ids`	string	No	-	Comma-separated bar IDs (max 100)
`category`	string	No	-	Filter by category slug (e.g., `sports-bar`, `cocktail-bar`)
`latitude`	float	No	-	Center latitude for radius search
`longitude`	float	No	-	Center longitude for radius search
`radius`	float	No	-	Search radius in miles (requires lat/lng)
`limit`	integer	No	100	Results limit (max 250)

Location Filtering

Option 1: Radius Search

?latitude=32.7765&longitude=-79.9311&radius=5

Option 2: Bounding Box (advanced)

?corner1[latitude]=32.7&corner1[longitude]=-80.0&corner2[latitude]=32.8&corner2[longitude]=-79.9

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://partner-api.barglance.com/api/v1/partner/bars?category=sports-bar&latitude=32.7765&longitude=-79.9311&radius=10&limit=50"

Example Response

{
  "bars": [
    {
      "id": "bar-123",
      "name": "The Tipsy Tap",
      "address": "123 Main St",
      "city": "Charleston",
      "state": "SC",
      "zip_code": "29401",
      "latitude": 32.7765,
      "longitude": -79.9311,
      "phone": "(843) 555-0100",
      "website": "https://tipsytap.com",
      "google_rating": 4.5,
      "google_ratings_total": 342,
      "primary_category": {
        "name": "Sports Bar",
        "slug": "sports-bar"
      },
      "categories": [
        {"name": "Sports Bar", "slug": "sports-bar"},
        {"name": "American", "slug": "american"}
      ],
      "hours": {
        "monday": [{"open": "11:00", "close": "23:00"}],
        "tuesday": [{"open": "11:00", "close": "23:00"}]
        // ... other days
      },
      "profile_picture_url": "https://cdn.barglance.com/bars/123/profile.jpg",
      "photos": [
        {"url": "https://cdn.barglance.com/bars/123/photo1.jpg"},
        {"url": "https://cdn.barglance.com/bars/123/photo2.jpg"}
      ],
      "occupancy": {
        "current_intensity": 65,
        "status": "moderate"
      }
    }
    // ... more bars
  ]
}

Get Bar Details

Retrieve comprehensive details for a specific bar.

Endpoint: GET /api/v1/partner/bars/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Bar ID

Example Request

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

Example Response

{
  "bar": {
    "id": "bar-123",
    "name": "The Tipsy Tap",
    "address": "123 Main St",
    "city": "Charleston",
    "state": "SC",
    "zip_code": "29401",
    "latitude": 32.7765,
    "longitude": -79.9311,
    "phone": "(843) 555-0100",
    "website": "https://tipsytap.com",
    "description": "Charleston's premier sports bar with 20+ TVs and craft beer selection.",
    "google_rating": 4.5,
    "google_ratings_total": 342,
    "price_level": 2,
    "primary_category": {
      "name": "Sports Bar",
      "slug": "sports-bar"
    },
    "categories": [
      {"name": "Sports Bar", "slug": "sports-bar"},
      {"name": "American", "slug": "american"}
    ],
    "hours": {
      "monday": [{"open": "11:00", "close": "23:00"}],
      "tuesday": [{"open": "11:00", "close": "23:00"}],
      "wednesday": [{"open": "11:00", "close": "23:00"}],
      "thursday": [{"open": "11:00", "close": "01:00"}],
      "friday": [{"open": "11:00", "close": "02:00"}],
      "saturday": [{"open": "10:00", "close": "02:00"}],
      "sunday": [{"open": "10:00", "close": "23:00"}]
    },
    "profile_picture_url": "https://cdn.barglance.com/bars/123/profile.jpg",
    "photos": [
      {"url": "https://cdn.barglance.com/bars/123/photo1.jpg"},
      {"url": "https://cdn.barglance.com/bars/123/photo2.jpg"}
    ],
    "occupancy": {
      "current_intensity": 65,
      "status": "moderate",
      "hourly_data": [
        {"hour": 17, "intensity": 45},
        {"hour": 18, "intensity": 65},
        {"hour": 19, "intensity": 85}
      ]
    },
    "events": [
      {
        "id": "event-456",
        "name": "Trivia Night",
        "description": "Weekly trivia with prizes!",
        "start_at": "2025-01-15T19:00:00Z",
        "end_at": "2025-01-15T22:00:00Z"
      }

  }
}

Get Bars by City

Retrieve bars, events, and occupancy data for a specific city.

Endpoint: GET /api/v1/partner/bars_by_city/:state/:city

Path Parameters

Parameter	Type	Required	Description
`state`	string	Yes	State abbreviation (e.g., `SC`)
`city`	string	Yes	City name (URL-encoded)

Query Parameters

Parameter	Type	Required	Default	Description
`group_slug`	string	No	-	Filter by group (e.g., `college-bars`)
`page`	integer	No	1	Page number
`per_page`	integer	No	20	Results per page

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://partner-api.barglance.com/api/v1/partner/bars_by_city/SC/Charleston?page=1&per_page=20"

Example Response

{
  "city": {
    "name": "Charleston",
    "state": "SC"
  },
  "bars": [
    {
      "id": "bar-123",
      "name": "The Tipsy Tap",
      "address": "123 Main St",
      // ... bar details
    }
  ],
  "events_today": [
    {
      "id": "event-789",
      "name": "Happy Hour",
      "start_at": "2025-01-15T17:00:00Z",
      "end_at": "2025-01-15T19:00:00Z",
      "bar": {
        "id": "bar-123",
        "name": "The Tipsy Tap"
      }
    }
  ],
  "busiest_bars": [
    {
      "id": "bar-456",
      "name": "Rooftop Lounge",
      "current_intensity": 92
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 98,
    "per_page": 20
  }
}

Get Events by City

Retrieve events for a specific city with date filtering.

Endpoint: GET /api/v1/partner/events/:state/:city

Path Parameters

Parameter	Type	Required	Description
`state`	string	Yes	State abbreviation (e.g., `SC`)
`city`	string	Yes	City name (URL-encoded)

Query Parameters

Parameter	Type	Required	Default	Description
`start_date`	string	No	Today	Filter by start date (ISO8601)
`end_date`	string	No	+30 days	Filter by end date (ISO8601)
`classification`	string	No	-	Filter by event type
`group_slug`	string	No	-	Filter by group (e.g., `college-bars`)
`page`	integer	No	1	Page number
`per_page`	integer	No	20	Results per page (max 100)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://partner-api.barglance.com/api/v1/partner/events/SC/Charleston?start_date=2025-01-01&per_page=10"

Example Response

{
  "events": [
    {
      "id": "event-123",
      "title": "Trivia Night",
      "description": "Weekly trivia with prizes!",
      "classification": "trivia",
      "start_at": "2025-01-15T19:00:00Z",
      "end_at": "2025-01-15T22:00:00Z",
      "created_at": "2025-01-01T10:00:00Z",
      "bar": {
        "id": "bar-123",
        "name": "The Tipsy Tap",
        "address": "123 Main St",
        "city": "Charleston",
        "state": "SC",
        "latitude": 32.7765,
        "longitude": -79.9311,
        "profile_picture_url": "https://cdn.barglance.com/bars/123/profile.jpg"
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 45,
    "per_page": 10
  }
}

Get Posts by City

Retrieve social posts for a specific city with date filtering.

Endpoint: GET /api/v1/partner/posts/:state/:city

Path Parameters

Parameter	Type	Required	Description
`state`	string	Yes	State abbreviation (e.g., `SC`)
`city`	string	Yes	City name (URL-encoded)

Query Parameters

Parameter	Type	Required	Default	Description
`start_date`	string	No	30 days ago	Filter by start date (ISO8601)
`end_date`	string	No	Today	Filter by end date (ISO8601)
`group_slug`	string	No	-	Filter by group (e.g., `college-bars`)
`page`	integer	No	1	Page number
`per_page`	integer	No	20	Results per page (max 100)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://partner-api.barglance.com/api/v1/partner/posts/SC/Charleston?per_page=10"

Example Response

{
  "posts": [
    {
      "id": "post-123",
      "text": "Great atmosphere tonight! 🍻",
      "created_at": "2025-01-15T20:30:00Z",
      "bar": {
        "id": "bar-123",
        "name": "The Tipsy Tap",
        "address": "123 Main St",
        "city": "Charleston",
        "state": "SC",
        "latitude": 32.7765,
        "longitude": -79.9311,
        "profile_picture_url": "https://cdn.barglance.com/bars/123/profile.jpg"
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 12,
    "total_count": 115,
    "per_page": 10
  }
}

Get City Feed

Retrieve social feed (posts and events) for a specific city.

Endpoint: GET /api/v1/partner/feed/:state/:city

Path Parameters

Parameter	Type	Required	Description
`state`	string	Yes	State abbreviation (e.g., `SC`)
`city`	string	Yes	City name (URL-encoded)

Query Parameters

Parameter	Type	Required	Default	Description
`page`	integer	No	1	Page number for posts
`per_page`	integer	No	20	Results per page

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://partner-api.barglance.com/api/v1/partner/feed/SC/Charleston?page=1&per_page=10"

Example Response

{
  "city": {
    "name": "Charleston",
    "state": "SC"
  },
  "posts": [
    {
      "id": "post-123",
      "content": "Great night at The Tipsy Tap! 🍻",
      "created_at": "2025-01-15T20:30:00Z",
      "user": {
        "id": "user-456",
        "username": "johndoe"
      },
      "bar": {
        "id": "bar-123",
        "name": "The Tipsy Tap"
      },
      "media": [
        {"url": "https://cdn.barglance.com/posts/123/photo.jpg"}
      ]
    }
  ],
  "events": [
    {
      "id": "event-789",
      "name": "Live Music Night",
      "description": "Local band performing!",
      "start_at": "2025-01-16T21:00:00Z",
      "end_at": "2025-01-16T23:00:00Z",
      "bar": {
        "id": "bar-789",
        "name": "Music Hall"
      }
    }
  ],
  "posts_pagination": {
    "current_page": 1,
    "total_pages": 12,
    "total_count": 234,
    "per_page": 20
  },
  "events_pagination": {
    "current_page": 1,
    "total_pages": 3,
    "total_count": 45,
    "per_page": 20
  }
}

Search

Search for bars and cities by name or address.

Endpoint: GET /api/v1/partner/search

Query Parameters

Parameter	Type	Required	Default	Description
`q`	string	Yes	-	Search query text
`latitude`	float	No	-	User latitude for distance sorting
`longitude`	float	No	-	User longitude for distance sorting
`page`	integer	No	1	Page number
`per_page`	integer	No	20	Results per page (max 100)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://partner-api.barglance.com/api/v1/partner/search?q=Tipsy&latitude=32.7765&longitude=-79.9311"

Example Response

{
  "results": [
    {
      "type": "bar",
      "id": "bar-123",
      "name": "The Tipsy Tap",
      "address": "123 Main St",
      "location": {
        "type": "Point",
        "coordinates": [-79.9311, 32.7765]
      },
      "price_level": 2,
      "distance": 0.5,
      "image_url": "https://cdn.barglance.com/bars/123/profile.jpg"
    },
    {
      "type": "city",
      "id": "city-456",
      "name": "Charleston, SC",
      "state": "SC",
      "location": {
        "type": "Point",
        "coordinates": [-79.9311, 32.7765]
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 2,
    "per_page": 20
  }
}