Users¶

Overview¶

The Users system manages user profiles, location data, and user discovery features on Jend-Z. This includes profile management, location-based user discovery, and user search functionality. All user management endpoints use the /api/users/ prefix.

User Model¶

The CustomUser model extends Django's AbstractUser with additional fields specific to Jend-Z:

Core Fields¶

id (UUID): Unique identifier
email (EmailField): Primary login field, must be unique
username (CharField): Secondary identifier, must be unique
display_name (CharField): Name displayed on the platform
password (CharField): Hashed password (minimum 8 characters)

Profile Fields¶

bio (TextField): User biography (optional)
website (URLField): Personal website (optional)
profile_picture (ImageField): Profile image (optional)
banner (ImageField): Profile banner image (optional)
is_verified (BooleanField): Account verification status

Relationship Status¶

relationship_status (CharField): Current relationship status

Available choices:

lonely_af - "Lonely af"
forever_alone - "Forever alone"
looking_for_love - "Looking for love"
taken - "Taken, sorry!"
emotionally_unavailable - "Emotionally unavailable"
waiting - "Waiting for the right person"
swiping - "Swiping endlessly"
career_married - "Married to my career"

Location Fields¶

latitude (DecimalField): Geographic latitude coordinate
longitude (DecimalField): Geographic longitude coordinate
location (ForeignKey): Reference to Location model for structured location data

Tracking Fields¶

created_at (DateTimeField): Account creation timestamp
updated_at (DateTimeField): Last profile update timestamp
referrer_code (CharField): Referral code used during registration

Profile Management¶

1. Get Current User Profile¶

Endpoint: GET /api/users/profile/

Authentication: Bearer token required

Response:

{
  "id": "uuid-string",
  "email": "user@example.com",
  "username": "unique_username",
  "display_name": "Display Name",
  "is_verified": false,
  "bio": "User bio",
  "profile_picture": "https://example.com/media/profile_pictures/image.jpg",
  "website": "https://userwebsite.com",
  "relationship_status": "looking_for_love",
  "banner": "https://example.com/media/users/banners/banner.jpg",
  "location": {
    "id": "location-uuid",
    "name": "Lagos, Nigeria"
  },
  "store": null,
  "owned_communities": [],
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

2. Update User Profile¶

Endpoint: PUT /api/users/profile/update/ or PATCH /api/users/profile/

Authentication: Bearer token required

Content-Type: multipart/form-data (for file uploads) or application/json

Request Body:

{
  "display_name": "New Display Name",
  "bio": "Updated bio",
  "website": "https://newwebsite.com",
  "relationship_status": "taken",
  "profile_picture": "new_image_file",
  "banner": "new_banner_file",
  "location": {
    "country": "Nigeria",
    "state": "Lagos State",
    "city": "Lagos",
    "longitude": 3.3792,
    "latitude": 6.5244
  }
}

Note: The is_verified field cannot be updated through this endpoint.

Location Update Behavior:

If location data is provided, the system will:
Search for an existing location matching the provided data
Create a new location if no match is found
Update existing location coordinates if provided
Assign the location to the user

3. Get User Profile by Username¶

Endpoint: GET /api/users/{username}

Authentication: Not required (public endpoint)

Response: Same as current user profile endpoint

Location Management¶

Update User Location¶

Endpoint: POST /api/users/update-location/

Authentication: Bearer token required

Description: Updates the user's location using structured location data, typically obtained from geocoding services like OpenStreetMap Nominatim.

Request Body:

{
  "country": "Nigeria",
  "state": "Lagos State",
  "county": "Lagos Mainland",
  "district": null,
  "city": "Lagos",
  "town": null,
  "village": null,
  "hamlet": null,
  "municipality": null,
  "suburb": "Yaba",
  "borough": null,
  "quarter": null,
  "neighbourhood": "Sabo",
  "road": "Herbert Macaulay Way",
  "building": null,
  "commercial": null,
  "amenity": null,
  "longitude": 3.3792,
  "latitude": 6.5244
}

Success Response:

{
  "message": "Location updated successfully",
  "location": {
    "id": "location-uuid",
    "name": "Herbert Macaulay Way"
  }
}

Frontend Integration Example: The frontend typically uses the browser's geolocation API combined with a reverse geocoding service:

// Get user's coordinates
navigator.geolocation.getCurrentPosition(async (position) => {
  const { latitude, longitude } = position.coords;

  // Reverse geocode using OpenStreetMap Nominatim
  const response = await axios.get(
    "https://nominatim.openstreetmap.org/reverse",
    {
      params: {
        lat: latitude,
        lon: longitude,
        format: "json",
        zoom: 19,
      },
      headers: {
        "User-Agent": "User-" + uuidv4(),
      },
    }
  );

  // Format for Jend-Z location structure
  const formattedLocation = {
    country: osmData?.address?.country || null,
    state: osmData?.address?.state || null,
    // ... map all location fields
    longitude,
    latitude,
  };

  // Update location on Jend-Z
  await api.post("/api/users/update-location/", formattedLocation);
});

Important: OpenStreetMap Nominatim requires a User-Agent header to prevent request blocking. Use a unique identifier like uuidv4() to ensure requests are properly identified.

User Discovery¶

1. Search Users¶

Endpoint: GET /api/users/search/

Authentication: Bearer token required

Description: Search for users by username or display name (used for mentions and user discovery).

Query Parameters:

query (required): Search term

Example: GET /api/users/search/?query=john

Response:

[
  {
    "id": "uuid-string",
    "username": "johnsmith",
    "display_name": "John Smith",
    "profile_picture": "https://example.com/media/profile_pictures/john.jpg"
  },
  {
    "id": "uuid-string",
    "username": "johnny_doe",
    "display_name": "Johnny Doe",
    "profile_picture": "https://example.com/media/profile_pictures/johnny.jpg"
  }
]

2. Nearby Users¶

Endpoint: GET /api/users/nearby-users/

Authentication: Bearer token required

Description: Returns users within a 100km radius of the current user's location.

Query Parameters:

page (optional): Page number for pagination
page_size (optional): Number of users per page (default: 10, max: 50)

Response:

{
  "count": 25,
  "next": "http://api.example.com/api/users/nearby-users/?page=3",
  "previous": "http://api.example.com/api/users/nearby-users/?page=1",
  "results": [
    {
      "id": "uuid-string",
      "email": "nearby@example.com",
      "username": "nearbyuser",
      "display_name": "Nearby User",
      "is_verified": true,
      "bio": "Lives nearby",
      "profile_picture": "https://example.com/media/profile_pictures/nearby.jpg",
      "website": null,
      "relationship_status": "single",
      "banner": null,
      "location": {
        "id": "location-uuid",
        "name": "Same City"
      },
      "store": null,
      "owned_communities": [],
      "created_at": "2024-01-01T12:00:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Prerequisites: User must have a location set to receive nearby users.

Profile Associations¶

Each user profile includes related content and business information:

Store Association¶

store (Object): User's store information if they own a store
Null Value: Returns null if user doesn't own a store
Usage: Display business information on user profiles

Community Ownership¶

owned_communities (Array): List of communities created by the user
Empty Array: Returns [] if user hasn't created any communities
Usage: Show leadership and community involvement

Verification System¶

is_verified (Boolean): Indicates official account verification
Admin Controlled: Only platform administrators can grant verification
Trust Indicator: Helps users identify authentic accounts
Enhanced Features: Verified users may have additional platform privileges

Location Privacy & Features¶

Coordinate Handling¶

Storage: Exact coordinates stored for proximity calculations
Privacy: Coordinates not exposed in public API responses
Precision: High precision support (8 decimal places) for accurate location matching

Location-Based Features¶

Nearby Users: Discover users within geographic proximity
Content Discovery: Location influences content recommendations
Local Commerce: Powers location-based store and product discovery
Community Mapping: Enables location-based community suggestions

Geographic Data Integration¶

Structured Locations: Integration with comprehensive location hierarchy
Auto-Assignment: Posts and stores inherit user location when appropriate
Geocoding Support: Compatible with standard geocoding services
Global Coverage: Supports international location data

Media Management¶

Profile Images¶

Profile Picture: Square/circular user avatar image
Banner Image: Rectangular cover/header image
Upload Support: Multipart form data upload
Storage Paths:
Profile pictures: profile_pictures/
Banners: users/banners/

Image Processing¶

Format Support: JPEG, PNG, GIF, WebP
URL Generation: Full URLs provided in API responses
Optimization: Automatic image processing for web delivery

Search & Discovery¶

User Search Capabilities¶

Username Search: Partial matching on username field
Display Name Search: Partial matching on display name
Case Insensitive: Search works regardless of case
Mention Support: Optimized for @mention functionality

Discovery Features¶

Location-Based: Find users in same geographic area
Community-Based: Discover users through shared communities
Content-Based: Find users through post interactions
Business Discovery: Locate store owners and entrepreneurs

Privacy Controls¶

Public Information¶

Username: Always public for mentions and discovery
Display Name: Public profile information
Profile Picture: Public avatar image
Bio: Public profile description
Verification Status: Public trust indicator

Controlled Information¶

Email: Private, used only for authentication and notifications
Exact Location: Coordinates used for proximity but not exposed
Personal Details: Contact information controlled by user

Location Privacy¶

Proximity Only: Location used for "nearby" features without revealing exact position
User Control: Users can choose whether to enable location-based features
Opt-Out: Users can disable location sharing while keeping account

Error Handling¶

Common Error Responses¶

User Not Found:

{
  "detail": "Not found."
}

Invalid Location Data:

{
  "longitude": ["Invalid coordinate value."],
  "latitude": ["Invalid coordinate value."]
}

Search Query Missing:

{
  "error": "Query parameter is required"
}

Permission Denied:

{
  "detail": "You do not have permission to perform this action."
}

HTTP Status Codes¶

200 OK: Successful request
400 Bad Request: Invalid request data
401 Unauthorized: Authentication required
403 Forbidden: Permission denied
404 Not Found: User or resource not found
500 Internal Server Error: Server error

Users¶

Overview¶

User Model¶

Core Fields¶

Profile Fields¶

Relationship Status¶

Location Fields¶

Tracking Fields¶

Profile Management¶

1. Get Current User Profile¶

2. Update User Profile¶

3. Get User Profile by Username¶

Location Management¶

Update User Location¶

User Discovery¶

1. Search Users¶

2. Nearby Users¶

User Relationships & Social Features¶

Profile Associations¶

Store Association¶

Community Ownership¶

Verification System¶

Location Privacy & Features¶

Coordinate Handling¶

Location-Based Features¶

Geographic Data Integration¶

Media Management¶

Profile Images¶

Image Processing¶

Search & Discovery¶

User Search Capabilities¶

Discovery Features¶

Privacy Controls¶

Public Information¶

Controlled Information¶

Location Privacy¶

Error Handling¶

Common Error Responses¶

HTTP Status Codes¶