Search API

Phase 2

This documentation is a preview. The Search API is currently in development and not yet available for use. Endpoints, parameters, and response structures are subject to change.

The Search API allows you to find store locations by proximity, keyword, or tags. It is the programmatic equivalent of the search bar on your storefront's store locator widget.

Search Locations

GET /v1/locations/search

Query Parameters

Parameter	Type	Required	Description	Default
query	string	No	Free-text search term (city name, zip code, or address). Geocoded server-side.	--
lat	number	No	Latitude of the search origin. Use with lng for coordinate-based searches.	--
lng	number	No	Longitude of the search origin. Use with lat.	--
radius	number	No	Search radius in the unit specified by unit.	25
unit	string	No	Unit of distance: mi (miles) or km (kilometers).	mi
tags	string	No	Comma-separated list of tags. Only locations matching all specified tags are returned.	--
limit	integer	No	Maximum number of results to return (max 100).	25
page	integer	No	Page number for pagination.	1

备注

You must provide either query or both lat and lng. If both are provided, the coordinate pair takes precedence over the text query.

Sample Request -- Search by Query

curl -X GET "https://api.scrollengine.com/v1/locations/search?query=Austin%20TX&radius=50&unit=mi&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Sample Request -- Search by Coordinates

curl -X GET "https://api.scrollengine.com/v1/locations/search?lat=30.2672&lng=-97.7431&radius=20&unit=mi&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",
      "tags": ["flagship", "repair-center"],
      "distance": {
        "value": 0.3,
        "unit": "mi"
      },
      "active": true
    },
    {
      "id": "loc_x9y8z7w6",
      "name": "North Austin Store",
      "address": {
        "line1": "8800 Research Blvd",
        "city": "Austin",
        "state": "TX",
        "zip": "78758",
        "country": "US"
      },
      "coordinates": {
        "lat": 30.3922,
        "lng": -97.7253
      },
      "phone": "+1-512-555-0234",
      "tags": ["retail"],
      "distance": {
        "value": 8.7,
        "unit": "mi"
      },
      "active": true
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 10,
    "total": 2,
    "search_origin": {
      "lat": 30.2672,
      "lng": -97.7431
    },
    "radius": 50,
    "unit": "mi"
  }
}

Response Fields

Location Fields

All standard location fields are returned (see the Location Object reference). The search response adds one extra field:

Field	Type	Description
distance	object	Distance from the search origin to this location. Contains value (numeric) and unit (mi or km).

Results are sorted by distance.value in ascending order (nearest first).

Meta Fields

Field	Type	Description
search_origin	object	The resolved lat/lng coordinates used as the center of the search.
radius	number	The search radius that was applied.
unit	string	The distance unit (mi or km).

Error Codes

Code	HTTP Status	Description
MISSING_SEARCH_PARAMS	400	Neither query nor lat/lng was provided.
GEOCODING_FAILED	422	The query value could not be resolved to coordinates.
INVALID_COORDINATES	400	The lat or lng values are out of valid range.
INVALID_RADIUS	400	The radius value is negative or exceeds the maximum allowed (500 mi / 800 km).

Next Steps

• Locations API -- Manage locations programmatically.
• Rate Limits -- Review request limits for search endpoints.