Sync API
After turning on Sync Mode, you can make an API call to our Sync API to synchronize your locations from an external source with Mapzy.
CAUTION: The synchronization process deletes all existing locations and opening times from your Mapzy account. Locations and opening times that are not included in the request payload are permanently deleted.
Authentication with API key
To authenticate, you need to send along your API key as a bearer token in the Authorization header. You can find your API key in your Mapzy settings. Make sure to send your request only over an encrypted connection (HTTPS) and never expose or share your API key publicly.
curl --request POST \
--header 'Authorization: Bearer b77a3260decc61f10f8z25ca8990elA'
If you accidently expose your API key, let us know (bonjour@mapzy.io) and we'll generate a new one for you. If you're self-hosting, you will need to re-generate it manually (see GitHub discussions for help with self-hosting).
API endpoint
You'll find the Sync API at this endpoint:
/api/v1/maps/:map_id/sync
If you're using the hosted version of Mapzy, the full URL is:
https://app.mapzy.io/api/v1/maps/:map_id/sync
If you're self-hosting, replace the host of the URL with your own host, e.g.:
https://example.com/api/v1/maps/:map_id/sync
Make sure to replace :map_id
with your actual Mapzy map ID, which you can find in the URL when you're logged in to your Mapzy account. It should look like this:
/dashboard/maps/m5Rgzb
where m5Rgzb
is your map ID.
You need to send a POST request to this URL with the correctly formatted JSON body containing an array of locations and their opening times to sync your locations into Mapzy.
Request payload
The request payload must be formatted as JSON and contain an array including at least one Location
object.
Location
object
The Location
object contains information about a single location and optionally an array of OpeningTime
objects.
name
(string, required)
The location's displayed name. For example, "Joe's Ravioli Factory".
address
(string, required)
The location's address. For example, "Krossener Straße 21, 10245 Berlin, Germany".
If you don't provide latitude and longitude, Mapzy geocodes this address to find the coordinates. If you do provide latitude and longitude, they are used as coordinates. However, the provided address is still displayed as the address.
latitude
(float, optional*)
The latitude of this location. For example: 52.510383475182095
If you provide a latitude value, you also need to provide a longitude value. Providing latitude and longitude values override the coordinates for the provided address.
longitude
(float, optional*)
The longitude of this location. For example: 13.459289627250147
If you provide a longitude value, you also need to provide a latitude value. Providing latitude and longitude values override the coordinates for the provided address.
description
(string, optional)
The location's displayed description.
opening_times
(OpeningTime[]
, optional)
The location's opening times. If you decide to provide opening times, you must provide exactly seven OpenTime
objects, one for each day of the week. Futhermore, week days can't appear more than once for a location. See below.
OpeningTime
object
The OpeningTime
object contains information about the opening time for a specific day.
day
(string, required)
The week of the day. Must be one of monday
, tuesday
, wednesday
, thursday
, friday
, saturday
, or sunday
.
opens_at
(string, required*)
The time of day when this location opens. Must be formatted like this HH:MM
. For example, 08:15
.
This value is required unless you provide a value for closed
or open_24h
. There is currently no timezone support, so make sure to provide local times.
closes_at
(string, optiorequirednal*)
The time of day when this location closes. Must be formatted like this HH:MM
. For example, 23:00
. There is currently no timezone support, so make sure to provide local times.
This value is required unless you provide a value for closed
or open_24h
.
closed
(boolean, optional)
If true
, marks this location as "closed" for this day and the opens_at
and closes_at
values are not displayed.
open_24h
(boolean, optional)
If true
, marks this location as "open 24h" for this day and the opens_at
and closes_at
values are not displayed.
Example request
Here's an example request putting it all together.
curl --request POST \
--url https://app.mapzy.io/api/v1/maps/m5Rgzb/sync \
--header 'Authorization: Bearer b77a3260decc61f10f8z25ca8990elA' \
--header 'Content-Type: application/json' \
--data '[
{
"name": "Joe Ravioli Factory",
"description": "If you like Joe Pasta, you will love Joe Ravioli.",
"address": "Krossener Straße 21, 10245 Berlin, Germany",
"latitude": "",
"longitude": "",
"opening_times": [
{
"day": "monday",
"opens_at": "10:00",
"closes_at": "20:00",
"closed": false,
"open_24h": false
},
{
"day": "tuesday",
"opens_at": "10:00",
"closes_at": "18:00",
"closed": false,
"open_24h": false
},
{
"day": "wednesday",
"opens_at": "11:00",
"closes_at": "18:00",
"closed": false,
"open_24h": false
},
{
"day": "thursday",
"opens_at": "11:00",
"closes_at": "18:00",
"closed": false,
"open_24h": false
},
{
"day": "friday",
"opens_at": "11:00",
"closes_at": "18:00",
"closed": false,
"open_24h": false
},
{
"day": "saturday",
"opens_at": "11:00",
"closes_at": "18:00",
"closed": false,
"open_24h": false
},
{
"day": "sunday",
"opens_at": "11:00",
"closes_at": "18:00",
"closed": false,
"open_24h": true
}
]
}
]'
For the sake of scrolling madness, this request only adds one location. As you can see, we've provided no values for latitude
and longitude
. Therefore, Mapzy will geocode the coordinates based on the address. We could have also left out the latitude
and longitude
keys completely.
Response (sucess)
If the request is succesful, Mapzy will return an empty reponse with the status code 204
(yes, we should improve this in the future).
Response (errors)
If something went wrong, Mapzy will return an error with some information about the error. Most likely, the HTTP status code will be 401
or 422
. It could also be 500
if you manage to hit a bug in our code.
The JSON body will look similar to this:
{
"error": {
"type": "ArgumentError",
"message": "Opening times day can't be blank"
}
}
401
(Unauthorized)
If you get this status code, double check that you have the right API key and formatted the Authorization header value correctly (see above).
422
(Unprocessable entity)
This is the most likely status code you will encounter, and it probably means that you forgot to provide a required value or malformatted something. In the response body, you should find more information about the nature of the error.
Other errors
If you receive a 204
response but your locations are not updated as expected, reach out to us at bonjour@mapzy.io. The data is processed in a background job after it passes initial validation, and there's a small possibility that something can go wrong there.