Integrations

Get store data with the API

What this article helps you do

Fetch active Mapstore locations from storefront JavaScript for a custom list or map. Do not use this procedure for the standard Mapstore block.

Before you start

  • Mapstore is installed and has active stores.
  • You can edit your Shopify theme’s JavaScript.
  • Your code runs in a shopper’s browser on your Shopify storefront.

Make a request

Use this path on your storefront:

/apps/mapstore/api/entities

Shopify forwards the request to Mapstore and adds the shop identity and signature. You do not need to set a shop parameter or an API key.

const response = await fetch('/apps/mapstore/api/entities?sort=name-a-z')

if (!response.ok) {
  throw new Error(`Mapstore request failed: ${response.status}`)
}

const data = await response.json()
console.log(data.entities)

If you changed the app-proxy path in Shopify, use that path instead of /apps/mapstore.

Available query parameters

Parameter Use
search Match a store name or address. A postal-code search finds nearby stores
filter Match any listed store filter; repeat the parameter or separate values with commas
country Match any listed two-letter country code; repeat the parameter or separate values with commas
includeCountries Use true to include available country codes in the response
sort updated-newest, updated-oldest, name-a-z, name-z-a, or row-order
zipRadiusKm Postal-code search radius from 1 to 500 kilometres. The default is 20

Read the response

The response contains:

  • entities contains the matching active stores
  • sortBy contains the requested sort setting
  • Mapstore includes countries when includeCountries=true
  • Mapstore includes zipSearchContext when it finds a postal code

Store records can include name, address, coordinates, contact details, filters, images, country code, and Google rating and hours data. They can also include custom fields, a custom marker image, and distance for postal-code searches. Mapstore omits optional values that are null or empty arrays.

Mapstore applies the plan limit for the shop before it returns locations.

Troubleshooting

Issue Fix
401 response Use the app-proxy path on your shop’s domain so Shopify signs the request.
404 response Check that Mapstore is installed and that the URL uses your shop’s configured app-proxy path.
No stores returned Make sure that stores are Active and match the request filters. Postal-code searches need coordinates.