> This page is for version 2024-10-01 (default). > For other versions, use one of these documentation indexes: > - 2024-10-01 (default): https://docs.getkard.com/2024-10-01/llms.txt > - Legacy: https://docs.getkard.com/legacy/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.getkard.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getkard.com/_mcp/server. # Get Locations By User GET https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}/locations Retrieve national and local geographic locations that a specified user has eligible in-store offers at. Use this endpoint to build out your [map-specific UX experiences](/2024-10-01/api/getting-started#c-discover-clos-near-you-map-view). Required scopes: `rewards:read` Reference: https://docs.getkard.com/api/rewards/locations ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Servers - `https://rewards-api.getkard.com` (Production, default) - `https://test-rewards-api.getkard.com` (Sandbox) ## Request ### Path parameters - `organizationId` (string, required) — Your issuer organization ID, provided by Kard - `userId` (string, required) — The ID of the user as defined on the issuers system ### Query parameters - `page[size]` (integer, optional) - `page[after]` (string, optional) - `page[before]` (string, optional) - `filter[name]` (string, optional) - `filter[city]` (string, optional) — Case-insensitive substring match on the location's city. Never defines the search area; applied as an additional constraint alongside a radius search when `filter[latitude]`/`filter[longitude]`/`filter[radius]` are also provided. - `filter[zipCode]` (string, optional) — Exact-match filter on the location's zip code. Never defines the search area; applied as an additional constraint alongside a radius search when `filter[latitude]`/`filter[longitude]`/`filter[radius]` are also provided. - `filter[state]` (enum, optional) — Exact-match filter on the location's state. Never defines the search area; applied as an additional constraint alongside a radius search when `filter[latitude]`/`filter[longitude]`/`filter[radius]` are also provided. - Allowed values: `AL`, `AK`, `AS`, `AZ`, `AR`, `CA`, `CO`, `CT`, `DE`, `DC`, `FM`, `FL`, `GA`, `GU`, `HI`, `ID`, `IL`, `IN`, `IA`, `KS`, `KY`, `LA`, `ME`, `MH`, `MD`, `MA`, `MI`, `MN`, `MS`, `MO`, `MT`, `NE`, `NV`, `NH`, `NJ`, `NM`, `NY`, `NC`, `ND`, `MP`, `OH`, `OK`, `OR`, `PW`, `PA`, `PR`, `RI`, `SC`, `SD`, `TN`, `TX`, `UT`, `VT`, `VI`, `VA`, `WA`, `WV`, `WI`, `WY` - `filter[category]` (enum, optional) — Category of merchant. Please use URL Encode for non single word categories. (Food & Beverage should be Food%20%26%20Beverage) - Allowed values: `Arts & Entertainment`, `Baby, Kids & Toys`, `Books & Digital Media`, `Clothing, Shoes & Accessories`, `Computers, Electronics & Software`, `Convenience`, `Gas`, `Department Stores`, `Food & Beverage`, `Health & Beauty`, `Home & Garden`, `Miscellaneous`, `Occasions & Gifts`, `Pets`, `Sports & Outdoors`, `Supplies & Services`, `Travel` - `filter[longitude]` (double, optional) — Longitude of the point to search around. Must be provided together with `filter[latitude]`; combine with `filter[radius]` to run a radius search. - `filter[latitude]` (double, optional) — Latitude of the point to search around. Must be provided together with `filter[longitude]`; combine with `filter[radius]` to run a radius search. - `filter[radius]` (integer, optional) — Radius in miles to search around the point given by `filter[latitude]`/`filter[longitude]` (default 10, minimum 1). Has no effect unless both latitude and longitude are also provided — it is ignored when only `filter[zipCode]`, `filter[city]`, or `filter[state]` is used, without lat/long. - `sort` (enum, optional) — If provided, response will be sorted by the specified fields. Defaults to newest first, equivalent to descending `createdDate`; when `filter[latitude]`/`filter[longitude]` are provided, locations are ordered by ascending distance from that point first, then newest first. - Allowed values: `locationName`, `-locationName` - `include` (string, optional) — CSV list of included resources in the response (e.g "offers,categories"). Allowed values are `offers` and `categories`. - `supportedComponents` (enum, optional) — UI component types to include in included offers. - Allowed values: `shortDescription`, `longDescription`, `baseReward`, `boostedReward`, `cta`, `tags`, `detailTags`, `logoFlare`, `progressBar` ## Response ### 200 - `data` (list of LocationData, required) - `links` (Links, required) — Related links to the API call - `included` (list of EligibilityLocationIncluded, optional) ## Errors ### 500 Internal Server Error - `errors` (list of ErrorObject, required) ### 400 Invalid Request - `errors` (list of ErrorObject, required) ### 404 Does Not Exist Error - `errors` (list of ErrorObject, required) ### 401 Unauthorized Error - `errors` (list of ErrorObject, required) ## Types ### LocationData - `type` ("location", required) - `id` (string, required) — Location ID in Kard's system - `attributes` (LocationAttributes, required) - `relationships` (LocationRelationships, optional) — Related resources to the offer ### Links Related links to the API call - `self` (string, required) - `prev` (string, optional) - `next` (string, optional) ### EligibilityLocationIncluded ### ErrorObject - `status` (string, required) — Status code returned from the request - `title` (string, required) — Name of error - `detail` (string, required) — Description of the specific occurance of the error - `source` (ErrorSource, optional) — An object containing a reference to the primary source of the error - `id` (string, optional) — The id of the resource which caused the error. Always returned for multi-status errors. ### LocationAttributes - `name` (string, required) - `address` (EligibilityLocationAddress, required) - `coordinates` (Coordinates, required) - `phone` (string, required) - `operationHours` (OperationHours, required) - `partnerIds` (list of LocationPartnerId, required) — List of ids associated with the location from third party partners. Only applicable for LOCAL locations. - `cuisine` (enum, required, nullable) — The kind of food or venue this location offers, for example "Pizza Restaurant". - Allowed values: `American Restaurant`, `Southern Restaurant`, `Cajun & Creole Restaurant`, `Southwestern Restaurant`, `BBQ Restaurant`, `Steakhouse`, `Burger Restaurant`, `Hot Dog Joint`, `Wings Joint`, `Fried Chicken Restaurant`, `Sandwich Shop`, `Deli`, `Diner`, `Hawaiian Restaurant`, `Canadian Restaurant`, `Mexican Restaurant`, `Taco Shop`, `Burrito Restaurant`, `Latin American Restaurant`, `Caribbean Restaurant`, `Jamaican Restaurant`, `Cuban Restaurant`, `Puerto Rican Restaurant`, `Brazilian Restaurant`, `Argentine Restaurant`, `Peruvian Restaurant`, `Colombian Restaurant`, `Venezuelan Restaurant`, `Salvadoran Restaurant`, `Honduran Restaurant`, `Italian Restaurant`, `Pizza Restaurant`, `Pasta Restaurant`, `French Restaurant`, `Creperie`, `Spanish Restaurant`, `Tapas Restaurant`, `Portuguese Restaurant`, `German Restaurant`, `Austrian Restaurant`, `Swiss Restaurant`, `Fondue Restaurant`, `British Restaurant`, `Fish & Chips Shop`, `Irish Restaurant`, `Belgian Restaurant`, `Dutch Restaurant`, `Scandinavian Restaurant`, `Eastern European Restaurant`, `Polish Restaurant`, `Russian Restaurant`, `European Restaurant`, `Mediterranean Restaurant`, `Greek Restaurant`, `Middle Eastern Restaurant`, `Lebanese Restaurant`, `Israeli Restaurant`, `Jewish Restaurant`, `Turkish Restaurant`, `Persian Restaurant`, `Egyptian Restaurant`, `Moroccan Restaurant`, `Armenian Restaurant`, `Georgian Restaurant`, `Falafel Restaurant`, `Kebab Shop`, `African Restaurant`, `Ethiopian Restaurant`, `Indian Restaurant`, `Pakistani Restaurant`, `Bangladeshi Restaurant`, `Sri Lankan Restaurant`, `Nepalese Restaurant`, `Afghan Restaurant`, `Asian Restaurant`, `Chinese Restaurant`, `Taiwanese Restaurant`, `Hong Kong Restaurant`, `Dim Sum Restaurant`, `Hot Pot Restaurant`, `Dumpling Restaurant`, `Noodle Shop`, `Japanese Restaurant`, `Sushi Restaurant`, `Ramen Restaurant`, `Yakitori Restaurant`, `Korean Restaurant`, `Mongolian Restaurant`, `Thai Restaurant`, `Vietnamese Restaurant`, `Filipino Restaurant`, `Malaysian Restaurant`, `Indonesian Restaurant`, `Singaporean Restaurant`, `Burmese Restaurant`, `Cambodian Restaurant`, `Australian Restaurant`, `Seafood Restaurant`, `Poke Restaurant`, `Salad Restaurant`, `Soup Restaurant`, `Breakfast Restaurant`, `Brunch Restaurant`, `Bagel Shop`, `Buffet`, `Fast Food Restaurant`, `Food Truck`, `Gastropub`, `Bakery`, `Cafe`, `Bubble Tea Shop`, `Juice Bar`, `Dessert Shop`, `Ice Cream Shop`, `Doughnut Shop`, `Bar`, `Sports Bar`, `Wine Bar`, `Winery`, `Brewery`, `Cocktail Bar`, `Distillery`, `Nightclub`, `Karaoke Bar`, `Comedy Club`, `Music Venue`, `Dance Club`, `Pool Hall`, `Casino`, `Bowling Alley`, `Movie Theater`, `Museum`, `Stadium`, `Theme Park`, `Sports & Recreation`, `Vegan Restaurant`, `Vegetarian Restaurant`, `Kosher Restaurant`, `Halal Restaurant`, `Gluten Free Restaurant`, `Healthy Restaurant` - `rating` (LocationRating, required, nullable) — Customer rating for this location. - `priceLevel` (string, required, nullable) — Typical price range for this location, rendered as dollar signs from "$" (least expensive) to "$$$$" (most expensive). ### LocationRelationships - `category` (RelationshipMultiple, required) - `offers` (RelationshipMultiple, required) ### CategoryIncluded - `attributes` (CategoryFields, required) - `id` (string, required) — id of the category - `type` ("category", required) ### ErrorSource - `pointer` (string, optional) — A JSON pointer to the value in the request document that caused the error - `parameter` (string, optional) — A string indicating which URI query parameter caused the error - `header` (string, optional) — A string indicating the name of a single request header which caused the error ### EligibilityLocationAddress - `street` (string, required) - `city` (string, required) - `state` (string, required) - `zipCode` (string, required) ### Coordinates - `longitude` (double, required) - `latitude` (double, required) ### OperationHours - `periods` (list of OperationPeriod, required) - `weekdayText` (list of string, required) ### LocationPartnerId - `type` (enum, required) - Allowed values: `google` - `id` (string, required) ### LocationRating Customer rating for a location. - `value` (double, required) — Restaurant star rating. Rating is out of 5. - `count` (integer, required, nullable) — Number of ratings the score is based on. Null when a count is not available. ### RelationshipMultiple - `data` (list of RelationshipData, required) ### CategoryFields - `name` (enum, required) — Name of the category - Allowed values: `Arts & Entertainment`, `Baby, Kids & Toys`, `Books & Digital Media`, `Clothing, Shoes & Accessories`, `Computers, Electronics & Software`, `Convenience`, `Gas`, `Department Stores`, `Food & Beverage`, `Health & Beauty`, `Home & Garden`, `Miscellaneous`, `Occasions & Gifts`, `Pets`, `Sports & Outdoors`, `Supplies & Services`, `Travel` ### OperationPeriod - `close` (OperationTime, required) - `open` (OperationTime, required) ### RelationshipData - `type` (string, required) — Type of document returned - `id` (string, required) — The ID of the related resource ### OperationTime - `day` (integer, required) - `time` (string, required) ## Examples **Response** ```json { "data": [ { "type": "location", "id": "5e27318c9b346f00087fba8l", "attributes": { "name": "Worlds Greatest Chicken", "address": { "street": "120 Main St", "city": "Philadelphia", "state": "PA", "zipCode": "19147" }, "coordinates": { "longitude": -75.1446869, "latitude": 39.9419429 }, "phone": "+1 (123) 555-8880", "operationHours": { "periods": [ { "close": { "day": 1, "time": "1700" }, "open": { "day": 1, "time": "0900" } }, { "close": { "day": 2, "time": "1700" }, "open": { "day": 2, "time": "0900" } }, { "close": { "day": 3, "time": "1700" }, "open": { "day": 3, "time": "0900" } }, { "close": { "day": 4, "time": "1700" }, "open": { "day": 4, "time": "0900" } }, { "close": { "day": 5, "time": "1700" }, "open": { "day": 5, "time": "0900" } } ], "weekdayText": [ "Monday: 9:00 AM – 5:00 PM", "Tuesday: 9:00 AM – 5:00 PM", "Wednesday: 9:00 AM – 5:00 PM", "Thursday: 9:00 AM – 5:00 PM", "Friday: 9:00 AM – 5:00 PM", "Saturday: Closed", "Sunday: Closed" ] }, "partnerIds": [ { "type": "google", "id": "3pafnweri4" } ], "cuisine": "Pizza Restaurant", "rating": { "value": 4.6, "count": 812 }, "priceLevel": "$$" }, "relationships": { "category": { "data": [ { "type": "category", "id": "65920081b524d126068de24a" } ] }, "offers": { "data": [ { "type": "standardOffer", "id": "5e27318c9b346f00087fbb5b" } ] } } } ], "links": { "self": "/v2/issuers/{organizationId}/users/{userId}/locations?page[size]=1&filter[latitude]=39.9419429&filter[longitude]=-75.1446869&filter[radius]=10&include=offers,categories", "prev": null, "next": "/v2/issuers/{organizationId}/users/{userId}/locations?page[after]=NDMyNzQyODI3OTQw&page[size]=1&filter[latitude]=39.9419429&filter[longitude]=-75.1446869&filter[radius]=10&include=offers,categories" }, "included": [ { "type": "category", "id": "65920081b524d126068de24a", "attributes": { "name": "Food & Beverage" } }, { "type": "standardOffer", "id": "5e27318c9b346f00087fbb5c", "attributes": { "name": "Worlds Greatest Chicken", "terms": "Worlds Greatest Chicken offers are only available within US Locations.", "purchaseChannel": [ "INSTORE" ], "userReward": { "type": "PERCENT", "value": 5.7 }, "startDate": "2022-01-01T05:00:00Z", "expirationDate": "2022-01-01T05:00:00Z", "minRewardAmount": { "type": "CENTS", "value": 500 }, "maxRewardAmount": { "type": "CENTS", "value": 2000 }, "minTransactionAmount": { "type": "CENTS", "value": 500 }, "maxTransactionAmount": { "type": "CENTS", "value": 2000 }, "maxRedemptions": 1, "isTargeted": true, "assets": [ { "url": "http://attribution.getkard.com/logos/breakfastbunny_logo.png?eventCode=IMPRESSION&type=offerAttribution&medium=BROWSE&offerId=629fc220b7a4290009a188ec&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZlcnJpbmdQYXJ0bmVyVXNlcklkIjoiNDM4MTAzIiwiaXNzdWVySWQiOiIwMDAwNDMyMSIsInR5cGUiOiJPRkZFUiIsInBheWxvYWQiOnsiand0VGltZXN0YW1wIjoiMjAyNi0wNC0yMyJ9fQ.4f9QmoGpgXVIXu9Tq8XFVcx7Rz0jptsYNYpmaIBszyc&state=eyJyYW5rIjoxLCJmaWx0ZXJzIjpbXX0%3D", "alt": "", "type": "IMG_VIEW" }, { "url": "https://attribution.getkard.com/public/banners/breakfast-bunny-banner.jpg?eventCode=VIEW&type=offerAttribution&medium=BROWSE&offerId=629fc220b7a4290009a188ec&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZlcnJpbmdQYXJ0bmVyVXNlcklkIjoiNDM4MTAzIiwiaXNzdWVySWQiOiIwMDAwNDMyMSIsInR5cGUiOiJPRkZFUiIsInBheWxvYWQiOnsiand0VGltZXN0YW1wIjoiMjAyNi0wNC0yMyJ9fQ.4f9QmoGpgXVIXu9Tq8XFVcx7Rz0jptsYNYpmaIBszyc&state=eyJyYW5rIjoxLCJmaWx0ZXJzIjpbXX0%3D", "alt": "", "type": "BANNER_VIEW" }, { "url": "https://attribution.getkard.com/public/franki/venue/a3f2c81d0b7e4a55-storefront.jpg?eventCode=IMPRESSION&type=offerAttribution&medium=BROWSE&offerId=629fc220b7a4290009a188ec&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZlcnJpbmdQYXJ0bmVyVXNlcklkIjoiNDM4MTAzIiwiaXNzdWVySWQiOiIwMDAwNDMyMSIsInR5cGUiOiJPRkZFUiIsInBheWxvYWQiOnsiand0VGltZXN0YW1wIjoiMjAyNi0wNC0yMyJ9fQ.4f9QmoGpgXVIXu9Tq8XFVcx7Rz0jptsYNYpmaIBszyc&state=eyJyYW5rIjoxLCJmaWx0ZXJzIjpbXX0%3D", "alt": "", "type": "LOCATION_IMG_VIEW" } ], "websiteUrl": "http://worldsgreatestchickent.test.com", "description": "Worlds Greatest Chicken brings you the tastiest crispy, double fried spicy chicken in the world." } } ] } ``` **SDK Code** ```python import requests url = "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/locations" querystring = {"page[size]":"1","filter[latitude]":"39.9419429","filter[longitude]":"-75.1446869","filter[radius]":"10","include":"offers,categories"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/locations?page%5Bsize%5D=1&filter%5Blatitude%5D=39.9419429&filter%5Blongitude%5D=-75.1446869&filter%5Bradius%5D=10&include=offers%2Ccategories'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/locations?page%5Bsize%5D=1&filter%5Blatitude%5D=39.9419429&filter%5Blongitude%5D=-75.1446869&filter%5Bradius%5D=10&include=offers%2Ccategories" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/locations?page%5Bsize%5D=1&filter%5Blatitude%5D=39.9419429&filter%5Blongitude%5D=-75.1446869&filter%5Bradius%5D=10&include=offers%2Ccategories") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/locations?page%5Bsize%5D=1&filter%5Blatitude%5D=39.9419429&filter%5Blongitude%5D=-75.1446869&filter%5Bradius%5D=10&include=offers%2Ccategories") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/locations?page%5Bsize%5D=1&filter%5Blatitude%5D=39.9419429&filter%5Blongitude%5D=-75.1446869&filter%5Bradius%5D=10&include=offers%2Ccategories', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/locations?page%5Bsize%5D=1&filter%5Blatitude%5D=39.9419429&filter%5Blongitude%5D=-75.1446869&filter%5Bradius%5D=10&include=offers%2Ccategories"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/locations?page%5Bsize%5D=1&filter%5Blatitude%5D=39.9419429&filter%5Blongitude%5D=-75.1446869&filter%5Bradius%5D=10&include=offers%2Ccategories")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```