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.