Get Location

Provider Enablement / Endpoints

Get Singular Location by Merchant

For a given merchant (identified by the appropriate merchant identifier received in the list merchants call), return a singular location belonging to that merchant. The provider_id returned here will be passed to subsequent calls that require a location provider ID. It therefore must contain only characters that are valid in a URL (ASCII). This is an advancement from our “List Locations” endpoint, however, the response payload is the same between the two. This will enable both GrubHub as well as the integrating partner look at one store individually, especially for troubleshooting purposes.

GrubHub will hit this endpoint to get a location from a given merchant.

Note that the the id here is not GrubHub’s internal id but rather your location ID as the provider. In short, it’s the ID that you return to us in the List Locations endpoint.

The endpoint should return information about each location, including address, hours, phone # etc…

Request Endpoint

GET /merchants/provider_merchant_id/location/provider_location_id

Example Response Body

{
  "updated_at": "2019-08-17T12:45:03Z",
  "location": {
        "active": true,
        "terminated": false,
        "accepts_tips_on_pickup": false,
        "accepts_tips_on_delivery": false,
        "fulfills_deliveries": true,
        "fulfills_pickups": true,
        "hours": {
          "sunday": [
            {
              "opens_at": "11:00",
              "closes_at": "15:00"
            }
          ],
          "monday": [
            {
              "opens_at": "09:00",
              "closes_at": "22:00"
            }
          ],
          "tuesday": [
            {
              "opens_at": "09:00",
              "closes_at": "22:00"
            }
          ],
          "wednesday": [
            {
              "opens_at": "09:00",
              "closes_at": "22:00"
            }
          ],
          "thursday": [
            {
              "opens_at": "09:00",
              "closes_at": "22:00"
            }
          ],
          "friday": [
            {
              "opens_at": "09:00",
              "closes_at": "22:00"
            }
          ],
          "saturday": [
            {
              "opens_at": "11:00",
              "closes_at": "15:00"
            }
          ]
        },
        "delivery_hours": {
          "sunday": [
            {
              "opens_at": "13:00",
              "closes_at": "15:00"
            }
          ],
          "monday": [
            {
              "opens_at": "12:00",
              "closes_at": "20:00"
            }
          ],
          "tuesday": [
            {
              "opens_at": "12:00",
              "closes_at": "20:00"
            }
          ],
          "wednesday": [
            {
              "opens_at": "12:00",
              "closes_at": "20:00"
            }
          ],
          "thursday": [
            {
              "opens_at": "12:00",
              "closes_at": "20:00"
            }
          ],
          "friday": [
            {
              "opens_at": "12:00",
              "closes_at": "20:00"
            }
          ],
          "saturday": [
            {
              "opens_at": "13:00",
              "closes_at": "15:00"
            }
          ]
        },
        "locality": "Cambridge",
        "name": "Siam Bistro Mass. Ave.",
        "phone": "9786431567",
        "postal_code": "02139",
        "provider_id": "946283",
        "region": "MA",
        "street_address": "860 Mass. Ave.",
        "lat": 42.403601,
        "lng": -71.0806558,
        "pickup_minimum_amount": 500,
        "delivery_fee_amount": 399,
        "delivery_minimum_amount": 500,
        "delivery_area": [
          [
            29.4999233,
            -95.2000998
          ],
          [
            29.5459873,
            -95.213478
          ],
          [
            29.5773502,
            -95.2206922
          ],
          [
            29.4929148,
            -95.1840069
          ]
        ]
    }
}

Example Response Schema

{
  "type": "object",
  "properties": {
    "updated_at": {
      "description": "An iso8601 datestamp in UTC of when the location list was last refreshed",
      "type": "string"
    },
    "locations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "location": {
            "type": "object",
            "properties": {
              "active": {
                "description": "Whether or not the location is able to accept orders. For example, this should be false if the location is experiencing ordering provider issues and is unable to accept orders",
                "type": "boolean"
              },
              "terminated": {
                "description": "Whether or not the location is permanently unavailable on the provider",
                "type": "boolean"
              },
              "accepts_tips_on_delivery": {
                "description": "Whether or not the location accepts tips on delivery orders",
                "type": "boolean"
              },
              "accepts_tips_on_pickup": {
                "description": "Whether or not the location accepts tips on pickup orders",
                "type": "boolean"
              },
              "extended_address": {
                "description": "Additional address information, e.g. 'Suite 100'",
                "type": "string"
              },
              "fulfills_deliveries": {
                "description": "Whether or not the location accepts delivery orders",
                "type": "boolean"
              },
              "fulfills_pickups": {
                "description": "Whether or not the location accepts pickup orders",
                "type": "boolean"
              },
              "hours": {
                "type": "object",
                "properties": {
                  "sunday": {
                    "type": ["array", "string", "null"],
                    "description": "An array containing zero or more time ranges; or the string 'closed'; or null, indicating the times are unknown",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location opens in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location closes in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "monday": {
                    "type": ["array", "string", "null"],
                    "description": "An array containing zero or more time ranges; or the string 'closed'; or null, indicating the times are unknown",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location opens in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location closes in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "tuesday": {
                    "type": ["array", "string", "null"],
                    "description": "An array containing zero or more time ranges; or the string 'closed'; or null, indicating the times are unknown",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location opens in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location closes in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "wednesday": {
                    "type": ["array", "string", "null"],
                    "description": "An array containing zero or more time ranges; or the string 'closed'; or null, indicating the times are unknown",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location opens in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location closes in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "thursday": {
                    "type": ["array", "string", "null"],
                    "description": "An array containing zero or more time ranges; or the string 'closed'; or null, indicating the times are unknown",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location opens in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location closes in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "friday": {
                    "type": ["array", "string", "null"],
                    "description": "An array containing zero or more time ranges; or the string 'closed'; or null, indicating the times are unknown",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location opens in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location closes in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "saturday": {
                    "type": ["array", "string", "null"],
                    "description": "An array containing zero or more time ranges; or the string 'closed'; or null, indicating the times are unknown",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location opens in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location closes in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  }
                },
                "required": [
                  "sunday",
                  "monday",
                  "tuesday",
                  "wednesday",
                  "thursday",
                  "friday",
                  "saturday"
                ]
              },
              "delivery_hours": {
                "type": "object",
                "properties": {
                  "sunday": {
                    "type": ["array", "string", "null"],
                    "description": "An array containing zero or more time ranges; or the string 'closed'; or null, indicating the times are unknown",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location starts accepting delivery orders in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location stops accepting delivery orders in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "monday": {
                    "type": ["array", "string", "null"],
                    "description": "An array containing zero or more time ranges; or the string 'closed'; or null, indicating the times are unknown",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location starts accepting delivery orders in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location stops accepting delivery orders in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "tuesday": {
                    "type": ["array", "string", "null"],
                    "description": "An array containing zero or more time ranges; or the string 'closed'; or null, indicating the times are unknown",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location starts accepting delivery orders in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location stops accepting delivery orders in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "wednesday": {
                    "type": ["array", "string", "null"],
                    "description": "An array containing zero or more time ranges; or the string 'closed'; or null, indicating the times are unknown",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location starts accepting delivery orders in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location stops accepting delivery orders in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "thursday": {
                    "type": ["array", "string", "null"],
                    "description": "An array containing zero or more time ranges; or the string 'closed'; or null, indicating the times are unknown",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location starts accepting delivery orders in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location stops accepting delivery orders in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "friday": {
                    "type": ["array", "string", "null"],
                    "description": "An array containing zero or more time ranges; or the string 'closed'; or null, indicating the times are unknown",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location starts accepting delivery orders in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location stops accepting delivery orders in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  },
                  "saturday": {
                    "type": ["array", "string", "null"],
                    "description": "An array containing zero or more time ranges; or the string 'closed'; or null, indicating the times are unknown",
                    "items": {
                      "type": "object",
                      "description": "An object containing opens_at and closes_at timestamps",
                      "items": {
                        "opens_at": {
                          "description": "The time (HH:MM) at which the location starts accepting delivery orders in local timezone",
                          "type": "timestamp"
                        },
                        "closes_at": {
                          "description": "The time (HH:MM) at which the location stops accepting delivery orders in local timezone",
                          "type": "timestamp"
                        }
                      },
                      "required": [
                        "closes_at",
                        "opens_at"
                      ]
                    }
                  }
                },
                "required": [
                  "sunday",
                  "monday",
                  "tuesday",
                  "wednesday",
                  "thursday",
                  "friday",
                  "saturday"
                ]
              },
              "provider_id": {
                "description": "The ID for the location that we will pass to you when ordering",
                "type": "string"
              },
              "locality": {
                "description": "The city/region of the location, e.g. 'Boston'",
                "type": "string"
              },
              "name": {
                "description": "The name of the location, e.g. 'Siam Bistro Pearl St.'",
                "type": "string"
              },
              "phone": {
                "description": "The phone number for the location",
                "type": "string"
              },
              "postal_code": {
                "description": "The postal code for the location",
                "type": "string"
              },
              "region": {
                "description": "The state the location is in",
                "type": "string"
              },
              "street_address": {
                "description": "The street address of the location",
                "type": "string"
              },
              "lat": {
                "description": "The latitude of the location",
                "type": "number"
              },
              "lng": {
                "description": "The longitude of the location",
                "type": "number"
              },
              "pickup_minimum_amount": {
                "description": "The minimum order total required for pickup, in cents",
                "type": "number"
              },
              "delivery_fee_amount": {
                "description": "The delivery fee charged, in cents",
                "type": "number"
              },
              "delivery_minimum_amount": {
                "description": "The minimum order total required for delivery, in cents",
                "type": "number"
              },
              "delivery_area": {
                "type": "array",
                "description": "An array of coordinates that defines the bounds for the delivery zone of the location",
                "items": {
                  "type": "array",
                  "description": "An array with the latitude and longitude coordinates of the location's delivery area",
                  "items": {
                    "lat": {
                      "description": "The latitudinal coordinate of the point",
                      "type": "number"
                    },
                    "lng": {
                      "description": "The longitudinal coordinate of the point",
                      "type": "number"
                    }
                  },
                  "required": [
                    "lat",
                    "lng"
                  ]
                }
              }
            },
            "required": [
              "active",
              "terminated",
              "accepts_tips_on_delivery",
              "accepts_tips_on_pickup",
              "locality",
              "name",
              "provider_id",
              "postal_code",
              "region",
              "street_address"
            ]
          }
        }
      }
    }
  },
  "required": [
    "locations",
    "updated_at"
  ]
}

Handling Hours

The "hours" attribute (and "delivery_hours", if appropriate) should contain an object with one key for each day of the week. Each day’s value can be one of three things:

  • an array of objects, where each object contains a open/close time pair indicating when the store is open (or delivery is available from that store)
  • the string "closed", indicating that the store is closed (or delivery is not available) that day
  • null, indicating that the information is unknown or unavailable.

A location may have more than one time pair per day. For instance, a restaurant that opens for lunch, closes in the early afternoon, and opens again for dinner might use the following pairs:

{
  "hours": {
    "wednesday": [
      {
        "opens_at": "11:00",
        "closes_at": "14:00"
      },
      {
        "opens_at": "17:00",
        "closes_at": "23:00"
      }
    ],
  }
}

A restaurant that stays open past midnight should split the time period into two segments, one for the day leading up to midnight and one for the following day. This location is open Tuesday night from 6pm until 2am:

{
  "hours": {
    "tuesday": [
      {
        "opens_at": "18:00",
        "closes_at": "24:00"
      }
    ],
    "wednesday": [
      {
        "opens_at": "0:00",
        "closes_at": "2:00"
      }
    ],
  }
}

If a location’s hours for a particular day are not known or not given by the provider, use the value null.

{
  "hours": {
    "monday": [
      {
        "opens_at": "18:00",
        "closes_at": "22:00"
      }
    ],
    "tuesday": null,
    "wednesday": null,
  }
}

However, if the location is known to be closed, use the value "closed". Here, Monday’s hours were not given by the provider, but the location is closed on Tuesday and Wednesday.

{
  "hours": {
    "monday": null,
    "tuesday": "closed",
    "wednesday": "closed",
  }
}

These examples have been shortened for clarity. Your response should always include all days of the week, even if some are null.