API Documentation

Technical reference for integrating with the PinPoint Store Locator API.

Overview

PinPoint provides a RESTful API for accessing store data. The API is primarily used by the storefront widget, but you can also use it for custom integrations.

Authentication

API requests are scoped to your Shopify shop. There are two authentication methods:

App Proxy (Recommended for Storefronts)

The storefront widget uses Shopify's App Proxy feature. Requests are automatically authenticated based on the shop context.

GET https://your-store.myshopify.com/apps/store-locator/api/public/stores/

Direct API Access

For server-to-server integrations, include your shop domain as a query parameter:

GET https://pinpoint-store-locator.replit.app/api/public/stores/?shop=your-store.myshopify.com

Public Endpoints

These endpoints are available for storefront and public integrations.

GET /api/public/stores/

Retrieve a list of active stores.

Query Parameters

Response

{
  "count": 50,
  "results": [
    {
      "id": 1,
      "name": "Downtown Store",
      "address": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zip_code": "10001",
      "country": "USA",
      "phone": "+1 (555) 123-4567",
      "website": "https://example.com",
      "latitude": "40.712776",
      "longitude": "-74.005974",
      "hours": "Mon-Fri 9am-5pm",
      "description": "Our flagship location",
      "image_url": "",
      "is_featured": true,
      "tags": [
        {"id": 1, "name": "Flagship", "color": "#667eea"}
      ],
      "custom_field_values": {},
      "distance": 2.5
    }
  ]
}

GET /api/public/settings/

Retrieve widget configuration settings.

GET /api/public/tags/

Retrieve available tags for filtering.

GET /api/public/filters/

Retrieve search filter definitions and options.

GET /api/public/products/

Retrieve products available for filtering (if product associations are enabled).

POST /api/public/analytics/track/

Track analytics events from the widget.

Request Body

{
  "event_type": "store_click",
  "store_id": 123,
  "session_id": "abc-123"
}

Event Types

• view - Widget loaded
• search - Search performed
• store_click - Store card clicked
• marker_click - Map marker clicked
• directions_click - Directions button clicked
• phone_click - Phone number clicked

POST /api/public/submissions/

Submit a new store suggestion (if external submissions are enabled).

Pagination

List endpoints return paginated results:

• count - Total number of results
• next - URL for next page (if available)
• previous - URL for previous page (if available)
• results - Array of items

Use ?page=2 to request specific pages.

Rate Limits

The API is subject to rate limiting to ensure fair usage:

• Public endpoints: 100 requests per minute per shop
• Analytics tracking: 1000 events per minute per shop

Error Responses