Custom pickup points via API

You can use Globe to integrate your own pickup points into the app. This is especially useful if you deliver to your own stores or operate a custom pickup point network.

To enable custom pickup points, you need to set up an API that returns pickup point data in a structured format. This guide explains how to build and configure your API to work seamlessly with Globe.

How it works

When a customer searches for pickup points near a specific location, Globe will send a POST request to your API endpoint. Your API should process the request and return a list of pickup points in the required format.

Request structure

Globe will send a POST request with the following details:

Headers:
- Content-Type: application/json
- X-Origin-Service: Globe Pickup Points (use this to verify requests come from Globe)
- any other headers from your settings in Globe
Body: A JSON object with these fields:

{
  "latitude": 50.08804,
  "longitude": 14.42076,
  "countryCode": "CZ",
  "shop": "store.myshopify.com"
}

latitude (float): Latitude of the customer’s location.
longitude (float): Longitude of the customer’s location.
countryCode (string): ISO 3166-1 alpha-2 country code of the customer’s location (e.g., CZ for the Czech Republic).
shop (string): The myshopify.com domain of the shop associated with the request.

Response structure

Your API should return a JSON response with the following structure, containing a maximum of 50 items sorted by distance from the requested location. If your API returns more than 50 items, only the first 50 will be processed by Globe.

{
  "data": [
    {
      "id": "cz-123456",
      "longitude": 14.42076,
      "latitude": 50.08804,
      "name": "Praha Pickup Point",
      "place": "Retail Store",
      "street": "Na Příkopě 12",
      "city": "Prague",
      "zip": "110 00",
      "country": "CZ",
      "pin": "https://example.com/pin-image.png",
      "openingHours": {
        "monday": "10:00 - 11:00, 12:00 - 15:00",
        "tuesday": "09:00 - 17:00"
      }
    }
  ]
}

Fields

id (string): Unique identifier for the pickup point.
longitude (float): Longitude of the pickup point’s location.
latitude (float): Latitude of the pickup point’s location.
name (string): The name of the pickup point.
place (string, optional): General location or neighborhood.
street (string): Street address.
city (string): City name.
zip (string): ZIP or postal code.
country (string): ISO 3166-1 alpha-2 country code (e.g., CZ for the Czech Republic).
pin (string, optional): URL of a 50x75 pixel image representing the pickup point pin on the map.
openingHours (object, optional): Operating hours for each day of the week. Days not included are assumed to be closed.

Example:

  {
    "monday": "10:00 - 11:00, 12:00 - 15:00",
    "tuesday": "09:00 - 17:00"
  }

Error handling

If an error occurs while processing the request, your API should return an appropriate HTTP status code and a JSON object with an error message. For example:

{
  "error": "Invalid request parameters"
}

Common errors

400 Bad Request: Missing or invalid parameters.
500 Internal Server Error: Unexpected server issues.

Example API implementation

Below is an example of how you could implement the required API in Node.js:

const express = require("express");
const app = express();
app.use(express.json());

app.post("/pickup-points", (req, res) => {
  const { latitude, longitude, countryCode, shop } = req.body;

  // Validate request body
  if (!latitude || !longitude || !countryCode || !shop) {
    return res.status(400).json({ error: "Missing required fields" });
  }

  // Example pickup points
  const pickupPoints = [
    {
      id: "cz-123456",
      longitude: 14.42076,
      latitude: 50.08804,
      name: "Praha Pickup Point",
      place: "Retail Store",
      street: "Na Příkopě 12",
      city: "Prague",
      zip: "110 00",
      country: "CZ",
      pin: "https://example.com/pin-image.png",
      openingHours: {
        monday: "10:00 - 11:00, 12:00 - 15:00",
        tuesday: "09:00 - 17:00"
      }
    }
  ];

  res.json({ data: pickupPoints });
});

app.listen(3000, () => {
  console.log("Custom Pickup Points API is running on port 3000");
});

Testing your API

Once your API is implemented, you can test it using tools like Postman or curl:

Example request

curl -X POST https://your-api.com/pickup-points \
-H "Content-Type: application/json" \
-H "X-Origin-Service: Globe Pickup Points" \
-d '{
  "latitude": 50.08804,
  "longitude": 14.42076,
  "countryCode": "CZ",
  "shop": "store.myshopify.com"
}'

Example response

{
  "data": [
    {
      "id": "cz-123456",
      "longitude": 14.42076,
      "latitude": 50.08804,
      "name": "Praha Pickup Point",
      "place": "Retail Store",
      "street": "Na Příkopě 12",
      "city": "Prague",
      "zip": "110 00",
      "country": "CZ",
      "pin": "https://example.com/pin-image.png",
      "openingHours": {
        "monday": "10:00 - 11:00, 12:00 - 15:00",
        "tuesday": "09:00 - 17:00"
      }
    }
  ]
}

Next steps

Deploy Your API: Host your API on a secure HTTPS-enabled server.
Add Your Custom Endpoints in Globe: Add a new carrier with a custom API endpoint.
Test Integration: Verify the pickup points are displayed correctly in the Globe app.

If you have questions or need assistance, contact our support team.