API Reference - User Locations

Link: https://support.brilliantdirectories.com/support/solutions/articles/12000108067

← Back to API Reference | Getting Started

User Locations

User Locations stores geographic location data for members, including zip code, county, state, and city information used for location-based searching and filtering on the directory.

Model name in URL: users_locations — DB table: users_locations

The User Locations Object

FieldTypeDescription
location_idintegerUnique location record ID (primary key, read-only)
user_idintegerID of the member this location belongs to (foreign key to users)
zip_idintegerID of the zip code record associated with this location
countystringCounty name for this location
statestringState abbreviation for this location
date_addedstringDate the location was added, formatted as YYYYMMDDHHmmss
zipstextComma-separated list of zip codes covered by this location entry
typestringLocation type (EG county, state, city; default county)
countrystringTwo-letter country code (default US)
citystringCity name for this location
migrate_stateintegerInternal migration status flag used during data migrations
Known Issue: The GET endpoints for this model are currently non-functional and may return a server error. POST create, PUT update, and DELETE work normally. This issue is being investigated.

List User Location Records

GET /api/v2/users_locations/get

Returns a paginated list of user location records.

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/users_locations/get?limit=25" \
  -H "X-Api-Key: your-api-key-here"
Known Issue: This endpoint is currently non-functional and may return a server error. This issue is being investigated.

Expected Response Format

Copy
{
  "status": "success",
  "message": [
    {
      "location_id": "1",
      "user_id": "42",
      "zip_id": "8291",
      "county": "Los Angeles County",
      "state": "CA",
      "date_added": "20240301120000",
      "zips": "90001,90002,90003",
      "type": "county",
      "country": "US",
      "city": "Los Angeles",
      "migrate_state": "0"
    },
    {
      "location_id": "2",
      "user_id": "42",
      "zip_id": "5104",
      "county": "Miami-Dade County",
      "state": "FL",
      "date_added": "20240302090000",
      "zips": "33101,33102,33109",
      "type": "county",
      "country": "US",
      "city": "Miami",
      "migrate_state": "0"
    }
  ],
  "total": "156",
  "current_page": 1,
  "total_pages": 7,
  "next_page": "MipfKjI1"
}

Retrieve a User Location Record

GET /api/v2/users_locations/get/{location_id}

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/users_locations/get/1" \
  -H "X-Api-Key: your-api-key-here"
Known Issue: This endpoint is currently non-functional and may return a server error. This issue is being investigated.

Expected Response Format

Copy
{
  "status": "success",
  "message": [
    {
      "location_id": "1",
      "user_id": "42",
      "zip_id": "8291",
      "county": "Los Angeles County",
      "state": "CA",
      "date_added": "20240301120000",
      "zips": "90001,90002,90003",
      "type": "county",
      "country": "US",
      "city": "Los Angeles",
      "migrate_state": "0"
    }
  ],
  "total": "156",
  "current_page": 1,
  "total_pages": 156
}

Create a User Location Record

POST /api/v2/users_locations/create

Example Request

Copy
curl -X POST "https://www.yourdomain.com/api/v2/users_locations/create" \
  -H "X-Api-Key: your-api-key-here" \
  -d "user_id=1" \
  -d "county=Los Angeles County" \
  -d "state=CA" \
  -d "city=Los Angeles" \
  -d "type=county" \
  -d "country=US"

Example Response

Copy
{
  "status": "success",
  "message": {
    "location_id": "157",
    "user_id": "1",
    "zip_id": null,
    "county": "Los Angeles County",
    "state": "CA",
    "date_added": null,
    "zips": null,
    "type": "county",
    "country": "US",
    "city": "Los Angeles",
    "migrate_state": null
  }
}

Update a User Location Record

PUT /api/v2/users_locations/update

Example Request

Copy
curl -X PUT "https://www.yourdomain.com/api/v2/users_locations/update" \
  -H "X-Api-Key: your-api-key-here" \
  -d "location_id=1" \
  -d "city=Santa Monica"

Example Response

Copy
{
  "status": "success",
  "message": {
    "location_id": "1",
    "user_id": "42",
    "zip_id": "8291",
    "county": "Los Angeles County",
    "state": "CA",
    "date_added": "20240301120000",
    "zips": "90001,90002,90003",
    "type": "county",
    "country": "US",
    "city": "Santa Monica",
    "migrate_state": "0"
  }
}

Delete a User Location Record

DELETE /api/v2/users_locations/delete

Example Request

Copy
curl -X DELETE "https://www.yourdomain.com/api/v2/users_locations/delete" \
  -H "X-Api-Key: your-api-key-here" \
  -d "location_id=1"

Example Response

Copy
{
  "status": "success",
  "message": "users_locations record was deleted"
}