You can retrieve location data through a GET request to the /location endpoint.

If a search query is provided, it will match against the name or address of a location.
If no query is provided, all locations will be returned.
The response body contains a JSON array of location objects.

Search Methods

Search by Geographic Coordinates

You can search for locations near a specific set of geographic coordinates.

curl -u '[email protected]:{password}' "https://www.keycafe.com/v0/location?latitude=9.2839043&longitude=-123.1053527&minimumHours=140" -H "Accept: application/json"

Parameters:

latitude (required): Latitude to center the search.
longitude (required): Longitude to center the search.
minimumHours (optional): Minimum number of hours the location must be open per week.

Behavior:

Results are sorted by distance from the specified coordinates.
Each location object includes the distance in kilometers.

Example Response

[
  { "name": "Corner Cafe", "distance": 3, ... },
  { "name": "Another Cafe", "distance": 5, ... }
]

Search by Geographic Bounding Box

You can define a rectangular area using geographic coordinates to retrieve locations within those bounds.

Request Example

curl -u '[email protected]:{password}' "https://www.keycafe.com/v0/location?northEastLat=9.2839043&northEastLng=-123.1053527&southWestLat=9.2839043&southWestLng=-123.1053527" -H "Accept: application/json"

Parameters:

northEastLat (required): Latitude of the northeast corner.
northEastLng (required): Longitude of the northeast corner.
southWestLat (required): Latitude of the southwest corner.
southWestLng (required): Longitude of the southwest corner.

Filter by User Access

You can restrict the results to locations where the authenticated user has access.

Request Example

curl -u '[email protected]:{password}' "https://www.keycafe.com/v0/location?access=true" -H "Accept: application/json"

Parameter

access (required): Set to true to filter results to locations where the user has an access.

Search by Postal Code

You can search for locations based on country and postal code.

Request Example

curl -u '[email protected]:{password}' "https://www.keycafe.com/v0/location?country=Canada&postalCode=A1A1A1" -H "Accept: application/json"

Parameters:

country (required): Country in which to search.
postalCode (required): Postal code for location search. In Canada and the UK, only the first three characters of the postal code are matched.
minimumHours (optional): Minimum number of open hours per week.

Example Response

[
  { "name": "Corner Cafe", ... },
  { "name": "Another Cafe", ... }
]

Filter by Private Locations (Enterprise Customers Only)

Enterprise customers can filter results to return only their private locations.

Request Example

curl -u '[email protected]:{password}' "https://www.keycafe.com/v0/location?private=true" -H "Accept: application/json"

Search by Organization ID

Retrieve all locations associated with a specific organization.

Request Example

curl -u '[email protected]:{password}' "https://www.keycafe.com/v0/location?organization=123456" -H "Accept: application/json"

Pagination

Results are paginated, with a maximum of 50 location per page. Additional pages can be accessed using the Link response header

Request Example

Link: <https://www.keycafe.com/v0/location?query=vancouver&page=2>; rel="next", <https://www.keycafe.com/v0/location?query=vancouver&page=5>; rel="last"

rel="first": URL to retrieve the first page of results.
rel="prev": URL to retrieve the previous page of results.
rel="next": URL to retrieve the next page of results.
rel="last": URL to retrieve the final page of results.