Skip to main content

Hashtag API

Author: Josh, Lead Backend Developer Last Updated: 2026-03-02 Version: v1.0

Base URL: https://api.nexgate.com/api/v1

Short Description: The Hashtag API enables content discovery through hashtags. Users can browse posts by hashtag with optional filters for products, shops, and events, and explore trending hashtags across configurable time windows.

Hints:

  • Hashtags are case-insensitive — #Dar and #dar resolve to the same tag
  • All hashtag data is extracted automatically from post content on publish
  • Trending is calculated by post count within the selected time window

Standard Response Format

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {}
}

HTTP Method Badge Standards

  • GET - GET - Green

Endpoints

1. Get Posts By Hashtag

Purpose: Retrieve paginated posts that contain a specific hashtag, with optional filtering by attachment type

Endpoint: GET {base_url}/e-social/hashtags/{hashtag}/posts

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Path Parameters:

Parameter Type Required Description
hashtag string Yes The hashtag to search (without #, e.g. MbeyaFashion)

Query Parameters:

Parameter Type Required Default Description
filter string No ALL Filter by attachment type. Accepted values: ALL, PRODUCTS, SHOPS, EVENTS
page integer No 1 Page number
size integer No 20 Number of posts per page

Request Headers:

Header Type Required Description
Authorization string Yes Bearer <token>
Content-Type string Yes application/json

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Posts retrieved",
  "action_time": "2026-03-02T10:30:45",
  "data": {
    "content": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "author": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "userName": "kibuti_dev",
          "firstName": "Kibuti",
          "lastName": "Dev",
          "profilePictureUrl": "https://cdn.nexgate.com/profiles/kibuti.jpg",
          "isVerified": false
        },
        "content": "New collection just dropped! #MbeyaFashion #Summer",
        "contentParsed": {
          "text": "New collection just dropped! #MbeyaFashion #Summer",
          "entities": [
            {
              "type": "HASHTAG",
              "text": "#MbeyaFashion",
              "startIndex": 29,
              "endIndex": 42,
              "hashtag": "mbeyafashion"
            }
          ]
        },
        "postType": "REGULAR",
        "status": "PUBLISHED",
        "attachments": {
          "products": [
            {
              "id": "789e0123-e89b-12d3-a456-426614174000",
              "name": "Summer Dress",
              "price": 45000.00,
              "imageUrl": "https://cdn.nexgate.com/products/dress.jpg",
              "shopName": "Mbeya Styles",
              "shopId": "abc12345-e89b-12d3-a456-426614174000",
              "inStock": true,
              "socialContext": null
            }
          ],
          "shops": [],
          "events": [],
          "buyTogetherGroups": [],
          "installmentPlans": [],
          "externalLink": null
        },
        "engagement": {
          "likesCount": 24,
          "commentsCount": 5,
          "repostsCount": 3,
          "bookmarksCount": 8,
          "viewsCount": 120,
          "sharesCount": 2,
          "quotesCount": 1
        },
        "publishedAt": "2026-03-01T14:22:00",
        "createdAt": "2026-03-01T14:20:00"
      }
    ],
    "pageable": {
      "pageNumber": 0,
      "pageSize": 20
    },
    "totalElements": 54,
    "totalPages": 3,
    "last": false,
    "first": true
  }
}

Filter Behavior:

Filter Value Returns
ALL All posts containing the hashtag
PRODUCTS Only posts with the hashtag that have attached products
SHOPS Only posts with the hashtag that have attached shops
EVENTS Only posts with the hashtag that have attached events

Standard Error Types:

  • 401 UNAUTHORIZED: Missing or invalid token
  • 500 INTERNAL_SERVER_ERROR: Unexpected server error

Error Response Example:

Unauthorized (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token has expired",
  "action_time": "2026-03-02T10:30:45",
  "data": "Token has expired"
}

Purpose: Retrieve the most used hashtags within a given time window, ordered by post count descending

Endpoint: GET {base_url}/e-social/hashtags/trending

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Query Parameters:

Parameter Type Required Default Description
window string No 24h Time window for trending calculation. Accepted values: 24h, 7d, 30d
limit integer No 15 Maximum number of trending hashtags to return

Request Headers:

Header Type Required Description
Authorization string Yes Bearer <token>
Content-Type string Yes application/json

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Trending hashtags",
  "action_time": "2026-03-02T10:30:45",
  "data": [
    {
      "hashtag": "mbeyafashion",
      "postCount": 312
    },
    {
      "hashtag": "daressalaamtech",
    "postCount": 278
    },
    {
      "hashtag": "tanzaniastartups",
      "postCount": 195
    },
    {
      "hashtag": "summer2026",
      "postCount": 143
    }
  ]
}

Response Fields:

Field Type Description
hashtag string The hashtag text (always lowercase, without #)
postCount long Number of posts using this hashtag within the selected time window

Window Behavior:

Window Value Looks Back
24h Last 24 hours — what's trending right now
7d Last 7 days — weekly trends
30d Last 30 days — monthly trends

Standard Error Types:

  • 401 UNAUTHORIZED: Missing or invalid token
  • 500 INTERNAL_SERVER_ERROR: Unexpected server error

3. Search Hashtags

Purpose: Search hashtags by prefix query, used in post composer to suggest similar hashtags while typing. Results are sorted by a weighted score combining recent activity and all-time popularity.

Endpoint: GET {base_url}/e-social/hashtags/search

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Query Parameters:

Parameter Type Required Default Description
q string Yes — Prefix query string (e.g. Mbe matches mbeyafashion, mbeyatech)
limit integer No 5 Maximum number of suggestions to return

Request Headers:

Header Type Required Description
Authorization string Yes Bearer <token>
Content-Type string Yes application/json

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Hashtag suggestions",
  "action_time": "2026-03-02T10:30:45",
  "data": [
    {
      "hashtag": "mbeyafashion",
      "postCount": 312
    },
    {
      "hashtag": "mbeyatech",
      "postCount": 89
    },
    {
      "hashtag": "mbeyafoods",
      "postCount": 45
    }
  ]
}

Response Fields:

Field Type Description
hashtag string Matched hashtag text (always lowercase, without #)
postCount long Total number of posts using this hashtag

Scoring & Sort Logic:

Results are sorted by a weighted score combining recency and popularity:

Post Age Score Weight
Posted within last 7 days 2 points per post
Older than 7 days 1 point per post

So a hashtag with 50 recent posts can outrank one with 200 old posts — fresh and trending tags float to the top naturally.

Empty Query Behavior: If q is empty or blank, returns an empty list immediately without querying the database.

Standard Error Types:

  • 401 UNAUTHORIZED: Missing or invalid token
  • 500 INTERNAL_SERVER_ERROR: Unexpected server error

Error Response Example:

Unauthorized (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token has expired",
  "action_time": "2026-03-02T10:30:45",
  "data": "Token has expired"
}

Quick Reference Guide

Endpoints Summary

Method Endpoint Description
GET /e-social/hashtags/{hashtag}/posts Get posts by hashtag with optional filter
GET /e-social/hashtags/trending Get trending hashtags by time window

Filter Values

ALL PRODUCTS SHOPS EVENTS

24h 7d 30d

Authentication

  • Bearer Token: Include Authorization: Bearer your_token in all headers

Data Format Standards

  • Dates: ISO 8601 format (2026-03-02T14:30:00)
  • IDs: UUID format (550e8400-e29b-41d4-a716-446655440000)
  • Hashtags: Always lowercase, without # symbol in API responses

No comments to display

Back to top