HungryHub API Documentation

This directory contains documentation for HungryHub’s public APIs.

Available APIs

Puma Public API

Puma is the search service providing restaurant search, suggestions, and filtering capabilities.

Key Features:

Restaurant search with advanced filters
Autocomplete suggestions
Group landing pages (curated collections)
Restaurant tags and filters
ML-powered ranking

Base URL: https://puma.hungryhub.com/graphql

Main Endpoints:

SearchRestaurants - Search for restaurants
SearchSuggestions - Get autocomplete suggestions
GroupLandingRestaurants - Get curated restaurant collections
FilterRestaurants - Get available filters with counts
GetRestaurantTags - Get restaurant tags (cuisines, locations, etc.)

Tiger Public API

Tiger is the core backend service providing personalized recommendations, homepage content, and user event tracking.

Key Features:

Personalized recommendations (AWS Personalize)
Homepage content management
Banners and promotional content
Home icons for quick navigation
User event tracking (views, clicks, bookings)
A/B testing experiment tracking

Base URL: https://tiger.hungryhub.com/graphql

Main Endpoints:

RecommendedForYou - Get personalized recommendations
PersonalizedRestaurants - Rerank restaurants for a user
GetHomepageSections - Get homepage sections
GetBanners - Get promotional banners
GetHomeIcons - Get home page icons
SendInteractionEvent - Track user interactions
SendImpressionEvent - Track item impressions

Quick Start

1. Basic Search Request (Puma)

curl -X POST https://puma.hungryhub.com/graphql \
  -H "Content-Type: application/json" \
  -H "X-Hh-Language: en" \
  -d '{
  "query": "query SearchRestaurants($input: SearchInput!) { SearchRestaurants(input: $input) { success data { id attributes { name slug location cuisine } } } }",
  "variables": {
    "input": {
      "keyword": "sushi",
      "pageSize": 10,
      "cityId": 1
    }
  }
}'

2. Get Personalized Recommendations (Tiger)

curl -X POST https://tiger.hungryhub.com/graphql \
  -H "Content-Type: application/json" \
  -H "X-Hh-Language: en" \
  -d '{
  "query": "query RecommendedForYou($input: RecommendedForYouInput!) { RecommendedForYou(input: $input) { success data { id attributes { name slug } } } }",
  "variables": {
    "input": {
      "userId": "12345",
      "cityId": 1,
      "pageSize": 10
    }
  }
}'

3. Track User Interaction (Tiger)

curl -X POST https://tiger.hungryhub.com/graphql \
  -H "Content-Type: application/json" \
  -d '{
  "query": "mutation SendInteractionEvent($input: InteractionEventInput!) { SendInteractionEvent(input: $input) { success message } }",
  "variables": {
    "input": {
      "userId": "12345",
      "itemId": "997",
      "eventType": "Click",
      "pageId": "search_page",
      "sessionId": "abc123",
      "timestamp": 1736152429359
    }
  }
}'

Common Headers

All GraphQL requests support these headers:

Content-Type: application/json (required)
X-Hh-Language: en|th|cn (optional, default: en) - For localized content
X-REQUEST-TYPE: GraphQL (optional) - Request type indicator

Response Format

All GraphQL responses follow this standardized format:

{
  "data": {
    "QueryOrMutationName": {
      "success": true,
      "message": "Success message",
      "data": [ /* response data */ ],
      "metaData": { /* optional metadata */ },
      "links": { /* optional pagination links */ }
    }
  }
}

Environment URLs

Development

Puma: http://localhost:4000/graphql
Tiger: http://localhost:4001/graphql

Staging

Puma: https://puma.hh-engineering.my.id/graphql
Tiger: https://tiger.hhstaging.dev/graphql

Production

Puma: https://puma.hungryhub.com/graphql
Tiger: https://tiger.hungryhub.com/graphql

Language Support

The API supports multiple languages via the X-Hh-Language header:

en - English (default)
th - Thai
cn - Chinese

Example:

curl -X POST https://puma.hungryhub.com/graphql \
  -H "X-Hh-Language: th" \
  -d '{ "query": "..." }'

Pagination

Most list queries support pagination with these parameters:

pageSize (Int): Number of items per page
pageNumber (Int): Page number (1-based)

The response includes pagination metadata:

{
  "data": [...],
  "metaData": {
    "totalRestaurants": 150
  },
  "links": {
    "next": "/graphql?page=2"
  }
}

Error Handling

GraphQL Errors

GraphQL errors are returned in the errors array:

{
  "errors": [
    {
      "message": "Invalid input: pageSize must be positive",
      "extensions": {
        "code": "BAD_USER_INPUT"
      }
    }
  ]
}

HTTP Status Codes

200 OK: Request processed (check success field in response)
400 Bad Request: Invalid GraphQL query syntax
500 Internal Server Error: Server error

Best Practices

Use pagination: Always set reasonable pageSize limits (recommended: 10-50)
Track user sessions: Include sessionId and userId for better personalization
Send events: Track user interactions for improved recommendations
Cache responses: Cache non-personalized content (banners, tags, sections)
Handle errors gracefully: Check both HTTP status and success field
Specify language: Always include X-Hh-Language header for consistent localization

Rate Limiting

Currently, there are no strict rate limits on public APIs. However, please:

Implement reasonable request throttling
Cache static content (tags, sections, banners)
Avoid excessive parallel requests
Contact the team if you need high-volume access

Support

For questions or issues with the API:

Documentation Issues: Open an issue in the repository
Technical Support: Contact the engineering team
Integration Help: Refer to code examples in /tools directory

HungryHub Knowledge Base