/api/data/contacts/popular
GETRetrieves your most frequently contacted addresses, ranked by usage.
Description
The `/api/data/contacts/popular` endpoint returns a list of your most frequently contacted addresses. This is useful for autocomplete features, quick-send interfaces, or analytics dashboards. The results are sorted by usage frequency in descending order.
Usage-Based Ranking
Contacts are ranked based on the number of messages sent to them. The most contacted addresses appear first in the list.
Limit Control
Use the `limit` parameter to control how many popular contacts are returned. This is especially useful for UI components like "Recent Contacts" or "Frequently Used" lists.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
limit |
integer | Optional | Maximum number of contacts to return. Range: 1-100 (default: 10) |
Response
Returns a JSON object containing the list of popular contacts and metadata.
Response Properties
contacts
array
Array of contact objects sorted by usage frequency (highest first).
contacts[].user_id
integer
Unique identifier for the contact.
contacts[].first_name
string
Contact's first name.
contacts[].last_name
string
Contact's last name.
contacts[].middle_name
string
Contact's middle name or initial.
contacts[].auto_address
string
Contact's QMail email address.
contacts[].description
string
Optional description or notes about the contact.
contacts[].sending_fee
number
Custom sending fee for this contact.
contacts[].beacon_id
string
Associated beacon identifier.
contacts[].message_count
integer
Number of messages sent to this contact.
count
integer
Number of contacts returned in this response.
limit
integer
The limit value used for this request.
Example Response
{
"contacts": [
{
"user_id": 15,
"first_name": "Alice",
"last_name": "Johnson",
"middle_name": "M",
"auto_address": "[email protected]",
"description": "Project manager",
"sending_fee": 1.5,
"beacon_id": "beacon-abc123",
"message_count": 47
},
{
"user_id": 8,
"first_name": "Bob",
"last_name": "Smith",
"middle_name": "",
"auto_address": "[email protected]",
"description": "Developer",
"sending_fee": 0,
"beacon_id": "",
"message_count": 32
},
{
"user_id": 23,
"first_name": "Carol",
"last_name": "Davis",
"middle_name": "R",
"auto_address": "[email protected]",
"description": "",
"sending_fee": 1.0,
"beacon_id": "beacon-def456",
"message_count": 18
}
],
"count": 3,
"limit": 10
}Example Response (Empty)
{
"contacts": [],
"count": 0,
"limit": 10
}Try it out
Examples
JavaScript (fetch)
const API_HOST = 'http://localhost:8080';
async function getPopularContacts(limit = 10) {
try {
const params = new URLSearchParams({ limit: limit });
const response = await fetch(`${API_HOST}/api/data/contacts/popular?${params}`);
const result = await response.json();
console.log(`Found ${result.count} popular contact(s):\n`);
result.contacts.forEach((contact, index) => {
console.log(`${index + 1}. ${contact.first_name} ${contact.last_name}`);
console.log(` Email: ${contact.auto_address}`);
console.log(` Messages sent: ${contact.message_count}\n`);
});
} catch (error) {
console.error('Error fetching popular contacts:', error);
}
}
getPopularContacts(5);
cURL
# Get top 10 popular contacts (default)
curl -X GET "http://localhost:8080/api/data/contacts/popular"
# Get top 5 popular contacts
curl -X GET "http://localhost:8080/api/data/contacts/popular?limit=5"
# Get top 20 popular contacts
curl -X GET "http://localhost:8080/api/data/contacts/popular?limit=20"
Go
package main
import (
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
"net/url"
)
const ApiHost = "http://localhost:8080"
type PopularContact struct {
UserID int `json:"user_id"`
FirstName string `json:"first_name"`
LastName string `json:"last_name"`
MiddleName string `json:"middle_name"`
AutoAddress string `json:"auto_address"`
Description string `json:"description"`
SendingFee float64 `json:"sending_fee"`
BeaconID string `json:"beacon_id"`
MessageCount int `json:"message_count"`
}
type PopularContactsResponse struct {
Contacts []PopularContact `json:"contacts"`
Count int `json:"count"`
Limit int `json:"limit"`
}
func main() {
params := url.Values{}
params.Add("limit", "5")
resp, err := http.Get(fmt.Sprintf("%s/api/data/contacts/popular?%s", ApiHost, params.Encode()))
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
var result PopularContactsResponse
if err := json.Unmarshal(body, &result); err != nil {
panic(err)
}
fmt.Printf("Found %d popular contact(s):\n\n", result.Count)
for i, contact := range result.Contacts {
fmt.Printf("%d. %s %s\n", i+1, contact.FirstName, contact.LastName)
fmt.Printf(" Email: %s\n", contact.AutoAddress)
fmt.Printf(" Messages sent: %d\n\n", contact.MessageCount)
}
}