Locations API
Phase 2
This documentation is a preview. The Locations API is currently in development and not yet available for use. Endpoints, request formats, and response structures are subject to change.
The Locations API provides full CRUD (Create, Read, Update, Delete) access to the store locations managed by Store Locator Map: SE.
Location Object
{
"id": "loc_a1b2c3d4",
"name": "Downtown Flagship",
"address": {
"line1": "123 Main Street",
"line2": "Suite 100",
"city": "Austin",
"state": "TX",
"zip": "78701",
"country": "US"
},
"coordinates": {
"lat": 30.2672,
"lng": -97.7431
},
"phone": "+1-512-555-0199",
"email": "downtown@example.com",
"hours": {
"monday": "9:00 AM - 6:00 PM",
"tuesday": "9:00 AM - 6:00 PM",
"wednesday": "9:00 AM - 6:00 PM",
"thursday": "9:00 AM - 8:00 PM",
"friday": "9:00 AM - 8:00 PM",
"saturday": "10:00 AM - 5:00 PM",
"sunday": "Closed"
},
"tags": ["flagship", "repair-center"],
"active": true,
"created_at": "2025-09-15T10:30:00Z",
"updated_at": "2025-11-02T14:22:00Z"
}
List All Locations
GET /v1/locations
Query Parameters
| Parameter | Type | Description | Default |
|---|---|---|---|
page | integer | Page number for pagination. | 1 |
per_page | integer | Number of results per page (max 100). | 25 |
active | boolean | Filter by active status. | -- |
tags | string | Comma-separated list of tags to filter by. | -- |
Sample Request
curl -X GET "https://api.scrollengine.com/v1/locations?page=1&per_page=10&tags=flagship" \
-H "Authorization: Bearer YOUR_API_KEY"
Sample Response
{
"success": true,
"data": [
{
"id": "loc_a1b2c3d4",
"name": "Downtown Flagship",
"address": {
"line1": "123 Main Street",
"line2": "Suite 100",
"city": "Austin",
"state": "TX",
"zip": "78701",
"country": "US"
},
"coordinates": {
"lat": 30.2672,
"lng": -97.7431
},
"phone": "+1-512-555-0199",
"email": "downtown@example.com",
"tags": ["flagship", "repair-center"],
"active": true
}
],
"meta": {
"page": 1,
"per_page": 10,
"total": 1
}
}
Get a Single Location
GET /v1/locations/{id}
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The unique location identifier (e.g., loc_a1b2c3d4). |
Sample Request
curl -X GET "https://api.scrollengine.com/v1/locations/loc_a1b2c3d4" \
-H "Authorization: Bearer YOUR_API_KEY"
Sample Response
{
"success": true,
"data": {
"id": "loc_a1b2c3d4",
"name": "Downtown Flagship",
"address": {
"line1": "123 Main Street",
"line2": "Suite 100",
"city": "Austin",
"state": "TX",
"zip": "78701",
"country": "US"
},
"coordinates": {
"lat": 30.2672,
"lng": -97.7431
},
"phone": "+1-512-555-0199",
"email": "downtown@example.com",
"hours": {
"monday": "9:00 AM - 6:00 PM",
"tuesday": "9:00 AM - 6:00 PM",
"wednesday": "9:00 AM - 6:00 PM",
"thursday": "9:00 AM - 8:00 PM",
"friday": "9:00 AM - 8:00 PM",
"saturday": "10:00 AM - 5:00 PM",
"sunday": "Closed"
},
"tags": ["flagship", "repair-center"],
"active": true,
"created_at": "2025-09-15T10:30:00Z",
"updated_at": "2025-11-02T14:22:00Z"
}
}
Create a Location
POST /v1/locations
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display name of the location. |
address | object | Yes | Address object with line1, city, state, zip, country. line2 is optional. |
coordinates | object | No | Object with lat and lng. If omitted, the API geocodes the address automatically. |
phone | string | No | Contact phone number. |
email | string | No | Contact email address. |
hours | object | No | Object with day-of-week keys and time-range string values. |
tags | array | No | Array of string tags for categorization. |
active | boolean | No | Whether the location is visible on the map. Defaults to true. |
Sample Request
curl -X POST "https://api.scrollengine.com/v1/locations" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Westside Mall Kiosk",
"address": {
"line1": "4500 West Boulevard",
"city": "Los Angeles",
"state": "CA",
"zip": "90064",
"country": "US"
},
"phone": "+1-310-555-0142",
"hours": {
"monday": "10:00 AM - 9:00 PM",
"tuesday": "10:00 AM - 9:00 PM",
"wednesday": "10:00 AM - 9:00 PM",
"thursday": "10:00 AM - 9:00 PM",
"friday": "10:00 AM - 10:00 PM",
"saturday": "10:00 AM - 10:00 PM",
"sunday": "11:00 AM - 7:00 PM"
},
"tags": ["mall", "kiosk"]
}'
Sample Response
{
"success": true,
"data": {
"id": "loc_e5f6g7h8",
"name": "Westside Mall Kiosk",
"address": {
"line1": "4500 West Boulevard",
"city": "Los Angeles",
"state": "CA",
"zip": "90064",
"country": "US"
},
"coordinates": {
"lat": 34.0330,
"lng": -118.4298
},
"phone": "+1-310-555-0142",
"tags": ["mall", "kiosk"],
"active": true,
"created_at": "2025-12-01T08:15:00Z",
"updated_at": "2025-12-01T08:15:00Z"
}
}
Update a Location
PATCH /v1/locations/{id}
Send only the fields you want to update. Omitted fields remain unchanged.
Sample Request
curl -X PATCH "https://api.scrollengine.com/v1/locations/loc_e5f6g7h8" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+1-310-555-0200",
"tags": ["mall", "kiosk", "seasonal"]
}'
Sample Response
{
"success": true,
"data": {
"id": "loc_e5f6g7h8",
"name": "Westside Mall Kiosk",
"phone": "+1-310-555-0200",
"tags": ["mall", "kiosk", "seasonal"],
"updated_at": "2025-12-05T11:00:00Z"
}
}
Delete a Location
DELETE /v1/locations/{id}
Sample Request
curl -X DELETE "https://api.scrollengine.com/v1/locations/loc_e5f6g7h8" \
-H "Authorization: Bearer YOUR_API_KEY"
Sample Response
{
"success": true,
"data": {
"id": "loc_e5f6g7h8",
"deleted": true
}
}
Error Codes
| Code | HTTP Status | Description |
|---|---|---|
LOCATION_NOT_FOUND | 404 | The specified location ID does not exist. |
VALIDATION_ERROR | 422 | One or more required fields are missing or invalid. |
GEOCODING_FAILED | 422 | The provided address could not be geocoded. Verify the address and try again. |
DUPLICATE_LOCATION | 409 | A location with the same name and address already exists. |
Next Steps
- Search API -- Search locations by proximity.
- Rate Limits -- Understand request limits per plan.