Get Locations By User

Retrieve national and local geographic locations that a specified user has eligible in-store offers at. To include local locations, add the includeLocal query parameter to your api call. Use this endpoint to build out your map-specific UX experiences. Please note that Longitude and Latitude fields are prioritized over State, City and Zipcode and are the recommended search pattern.

Required scopes: rewards:read

Path parameters

organizationIdstringRequired

Your issuer organization ID, provided by Kard

userIdstringRequired

The ID of the user as defined on the issuers system

Query parameters

page[size]integerOptional

page[after]stringOptional

page[before]stringOptional

filter[name]stringOptional

filter[city]stringOptional

filter[zipCode]stringOptional

filter[state]enumOptional

filter[category]enumOptional

Category of merchant. Please use URL Encode for non single word categories. (Food & Beverage should be Food%20%26%20Beverage)

filter[longitude]doubleOptional

filter[latitude]doubleOptional

filter[radius]integerOptional

sort"locationName" or "-locationName"Optional

If provided, response will be sorted by the specified fields

Allowed values: locationName-locationName

includestringOptional

CSV list of included resources in the response (e.g “offers,categories”). Allowed values are offers and categories.

Response

This endpoint returns an object.

datalist of objects

linksobject

Errors

1 curl -G https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}/locations \ 2 -H "Authorization: Bearer <token>" \ 3 -d "page[size]"=1 \ 4 -d "filter[latitude]"=39.9419429 \ 5 -d "filter[longitude]"=-75.1446869 \ 6 -d "filter[radius]"=10 \ 7 --data-urlencode include=offers,categories

1 { 2 "data": [ 3 { 4 "type": "location", 5 "id": "5e27318c9b346f00087fba8l", 6 "attributes": { 7 "name": "Worlds Greatest Chicken", 8 "address": { 9 "street": "120 Main St", 10 "city": "Philadelphia", 11 "state": "PA", 12 "zipCode": "19147" 13 }, 14 "coordinates": { 15 "longitude": -75.1446869, 16 "latitude": 39.9419429 17 }, 18 "phone": "+1 (123) 555-8880", 19 "operationHours": { 20 "periods": [ 21 { 22 "close": { 23 "day": 1, 24 "time": "1700" 25 }, 26 "open": { 27 "day": 1, 28 "time": "0900" 29 } 30 }, 31 { 32 "close": { 33 "day": 2, 34 "time": "1700" 35 }, 36 "open": { 37 "day": 2, 38 "time": "0900" 39 } 40 }, 41 { 42 "close": { 43 "day": 3, 44 "time": "1700" 45 }, 46 "open": { 47 "day": 3, 48 "time": "0900" 49 } 50 }, 51 { 52 "close": { 53 "day": 4, 54 "time": "1700" 55 }, 56 "open": { 57 "day": 4, 58 "time": "0900" 59 } 60 }, 61 { 62 "close": { 63 "day": 5, 64 "time": "1700" 65 }, 66 "open": { 67 "day": 5, 68 "time": "0900" 69 } 70 } 71 ], 72 "weekdayText": [ 73 "Monday: 9:00 AM – 5:00 PM", 74 "Tuesday: 9:00 AM – 5:00 PM", 75 "Wednesday: 9:00 AM – 5:00 PM", 76 "Thursday: 9:00 AM – 5:00 PM", 77 "Friday: 9:00 AM – 5:00 PM", 78 "Saturday: Closed", 79 "Sunday: Closed" 80 ] 81 } 82 }, 83 "relationships": { 84 "category": { 85 "data": [ 86 { 87 "type": "category", 88 "id": "65920081b524d126068de24a" 89 } 90 ] 91 }, 92 "offers": { 93 "data": [ 94 { 95 "type": "purchaseCountOffer", 96 "id": "5e27318c9b346f00087fbb5b" 97 } 98 ] 99 } 100 } 101 } 102 ], 103 "links": { 104 "self": "/v2/issuers/{organizationId}/users/{userId}/locations?page[size]=1&filter[latitude]=39.9419429&filter[longitude]=-75.1446869&filter[radius]=10&include=offers,categories", 105 "prev": null, 106 "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" 107 }, 108 "included": [ 109 { 110 "type": "category", 111 "id": "65920081b524d126068de24a", 112 "attributes": { 113 "name": "Food & Beverage" 114 } 115 }, 116 { 117 "type": "purchaseCountOffer", 118 "id": "5e27318c9b346f00087fbb5c", 119 "attributes": { 120 "name": "Worlds Greatest Chicken", 121 "terms": "Worlds Greatest Chicken offers are only available within US Locations.", 122 "purchaseChannel": [ 123 "INSTORE" 124 ], 125 "userReward": { 126 "type": "PERCENT", 127 "value": 5.7 128 }, 129 "startDate": "2022-01-01T05:00:00Z", 130 "expirationDate": "2022-01-01T05:00:00Z", 131 "minRewardAmount": { 132 "type": "CENTS", 133 "value": 500 134 }, 135 "maxRewardAmount": { 136 "type": "CENTS", 137 "value": 2000 138 }, 139 "minTransactionAmount": { 140 "type": "CENTS", 141 "value": 500 142 }, 143 "maxTransactionAmount": { 144 "type": "CENTS", 145 "value": 2000 146 }, 147 "maxRedemptions": 1, 148 "isTargeted": true, 149 "assets": [ 150 { 151 "type": "LOGO_IMAGE", 152 "url": "http://assets.getkard.com/logo/img?attribution-tokens", 153 "alt": "Worlds Greatest Chicken Logo Image" 154 }, 155 { 156 "type": "BANNER_IMAGE", 157 "url": "http://assets.getkard.com/banner/img?attribution-tokens", 158 "alt": "Worlds Greatest Chicken Banner Image" 159 } 160 ], 161 "websiteUrl": "http://worldsgreatestchickent.test.com", 162 "description": "Worlds Greatest Chicken brings you the tastiest crispy, double fried spicy chicken in the world." 163 } 164 } 165 ] 166 }

1	curl -G https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}/locations \
2	-H "Authorization: Bearer <token>" \
3	-d "page[size]"=1 \
4	-d "filter[latitude]"=39.9419429 \
5	-d "filter[longitude]"=-75.1446869 \
6	-d "filter[radius]"=10 \
7	--data-urlencode include=offers,categories

1	{
2	"data": [
3	{
4	"type": "location",
5	"id": "5e27318c9b346f00087fba8l",
6	"attributes": {
7	"name": "Worlds Greatest Chicken",
8	"address": {
9	"street": "120 Main St",
10	"city": "Philadelphia",
11	"state": "PA",
12	"zipCode": "19147"
13	},
14	"coordinates": {
15	"longitude": -75.1446869,
16	"latitude": 39.9419429
17	},
18	"phone": "+1 (123) 555-8880",
19	"operationHours": {
20	"periods": [
21	{
22	"close": {
23	"day": 1,
24	"time": "1700"
25	},
26	"open": {
27	"day": 1,
28	"time": "0900"
29	}
30	},
31	{
32	"close": {
33	"day": 2,
34	"time": "1700"
35	},
36	"open": {
37	"day": 2,
38	"time": "0900"
39	}
40	},
41	{
42	"close": {
43	"day": 3,
44	"time": "1700"
45	},
46	"open": {
47	"day": 3,
48	"time": "0900"
49	}
50	},
51	{
52	"close": {
53	"day": 4,
54	"time": "1700"
55	},
56	"open": {
57	"day": 4,
58	"time": "0900"
59	}
60	},
61	{
62	"close": {
63	"day": 5,
64	"time": "1700"
65	},
66	"open": {
67	"day": 5,
68	"time": "0900"
69	}
70	}
71	],
72	"weekdayText": [
73	"Monday: 9:00 AM – 5:00 PM",
74	"Tuesday: 9:00 AM – 5:00 PM",
75	"Wednesday: 9:00 AM – 5:00 PM",
76	"Thursday: 9:00 AM – 5:00 PM",
77	"Friday: 9:00 AM – 5:00 PM",
78	"Saturday: Closed",
79	"Sunday: Closed"
80	]
81	}
82	},
83	"relationships": {
84	"category": {
85	"data": [
86	{
87	"type": "category",
88	"id": "65920081b524d126068de24a"
89	}
90	]
91	},
92	"offers": {
93	"data": [
94	{
95	"type": "purchaseCountOffer",
96	"id": "5e27318c9b346f00087fbb5b"
97	}
98	]
99	}
100	}
101	}
102	],
103	"links": {
104	"self": "/v2/issuers/{organizationId}/users/{userId}/locations?page[size]=1&filter[latitude]=39.9419429&filter[longitude]=-75.1446869&filter[radius]=10&include=offers,categories",
105	"prev": null,
106	"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"
107	},
108	"included": [
109	{
110	"type": "category",
111	"id": "65920081b524d126068de24a",
112	"attributes": {
113	"name": "Food & Beverage"
114	}
115	},
116	{
117	"type": "purchaseCountOffer",
118	"id": "5e27318c9b346f00087fbb5c",
119	"attributes": {
120	"name": "Worlds Greatest Chicken",
121	"terms": "Worlds Greatest Chicken offers are only available within US Locations.",
122	"purchaseChannel": [
123	"INSTORE"
124	],
125	"userReward": {
126	"type": "PERCENT",
127	"value": 5.7
128	},
129	"startDate": "2022-01-01T05:00:00Z",
130	"expirationDate": "2022-01-01T05:00:00Z",
131	"minRewardAmount": {
132	"type": "CENTS",
133	"value": 500
134	},
135	"maxRewardAmount": {
136	"type": "CENTS",
137	"value": 2000
138	},
139	"minTransactionAmount": {
140	"type": "CENTS",
141	"value": 500
142	},
143	"maxTransactionAmount": {
144	"type": "CENTS",
145	"value": 2000
146	},
147	"maxRedemptions": 1,
148	"isTargeted": true,
149	"assets": [
150	{
151	"type": "LOGO_IMAGE",
152	"url": "http://assets.getkard.com/logo/img?attribution-tokens",
153	"alt": "Worlds Greatest Chicken Logo Image"
154	},
155	{
156	"type": "BANNER_IMAGE",
157	"url": "http://assets.getkard.com/banner/img?attribution-tokens",
158	"alt": "Worlds Greatest Chicken Banner Image"
159	}
160	],
161	"websiteUrl": "http://worldsgreatestchickent.test.com",
162	"description": "Worlds Greatest Chicken brings you the tastiest crispy, double fried spicy chicken in the world."
163	}
164	}
165	]
166	}