--- title: "Get Locations By User" method: GET path: "/v2/issuers/{organizationId}/users/{userId}/locations" tags: ["users > Rewards"] --- # Get Locations By User `GET /v2/issuers/{organizationId}/users/{userId}/locations` ## Request - Base URL: `https://rewards-api.getkard.com` - URL: `https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}/locations` - Auth: HTTP bearer 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` ## 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 - `page[after]` string - `page[before]` string - `filter[name]` string - `filter[city]` string - `filter[zipCode]` string - `filter[state]` '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]` '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': Category of merchant. Please use URL Encode for non single word categories. (Food & Beverage should be Food%20%26%20Beverage) - `filter[longitude]` number, double - `filter[latitude]` number, double - `filter[radius]` integer - `sort` 'locationName' | '-locationName' - `include` string - `supportedComponents` 'shortDescription' | 'longDescription' | 'baseReward' | 'boostedReward' | 'cta' | 'tags' | 'detailTags' | 'logoFlare' | 'progressBar': Available UI component types for offers ## Response `200` Response with status 200 - UsersRewardsLocationsResponseObject - `data` UsersRewardsLocationData[], required - `type` 'location', required - `id` string, required: The unique identifier for a document in the database - `attributes` UsersRewardsLocationAttributes, required - `name` string, required - `address` UsersRewardsEligibilityLocationAddress, required - `street` string, required - `city` string, required - `state` string, required - `zipCode` string, required - `coordinates` UsersRewardsCoordinates, required - `longitude` number, double, required - `latitude` number, double, required - `phone` string, required - `operationHours` UsersRewardsOperationHours, required - `periods` UsersRewardsOperationPeriod[], required - `close` UsersRewardsOperationTime, required - `day` integer, required - `time` string, required - `open` UsersRewardsOperationTime, required - `day` integer, required - `time` string, required - `weekdayText` string[], required - `partnerIds` UsersRewardsLocationPartnerId[], required: List of ids associated with the location from third party partners. Only applicable for LOCAL locations. - `type` 'google', required - `id` string, required - `cuisine` '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', required: The kind of food or venue a location offers, for example "Pizza Restaurant". - `rating` UsersRewardsLocationRating, required: Customer rating for a location. - `value` number, double, required: Restaurant star rating. Rating is out of 5. - `count` integer, nullable, required: Number of ratings the score is based on. Null when a count is not available. - `priceLevel` string, nullable, required: Typical price range for this location, rendered as dollar signs from "$" (least expensive) to "$$$$" (most expensive). - `relationships` UsersRewardsLocationRelationships - `offers` CommonsRelationshipMultiple, required - `data` CommonsRelationshipData[], required - `type` string, required: Type of document returned - `id` string, required: The ID of the related resource - `category` CommonsRelationshipMultiple, required - `data` CommonsRelationshipData[], required - `type` string, required: Type of document returned - `id` string, required: The ID of the related resource - `links` CommonsLinks, required: Related links to the API call - `self` string, required - `prev` string - `next` string - `included` UsersRewardsEligibilityLocationIncluded[] - union - UsersRewardsOfferDataUnion - `type` 'standardOffer', required: Discriminator value: standardOffer - `id` string, required: The unique identifier for a document in the database - `attributes` UsersRewardsStandardOfferFields, required - `terms` string, required: Terms and conditions on offer - `maxRedemptions` integer: Maximum times cardholder can redeem offer, if applicable - `name` string, required: Name of offer - `purchaseChannel` CommonsPurchaseChannel[], required - `userReward` UsersRewardsCommission, required - `type` 'FLAT' | 'PERCENT', required: Type of commission on offer (% or a flat $) - `value` number, double, required - `assets` UsersRewardsAsset[], required: Assets associated with offer - `type` string, required: What the asset shows. `IMG_VIEW` is the merchant logo, `BANNER_VIEW` a promotional banner, and `LOCATION_IMG_VIEW` a photo of the location. New values may be added over time. - `url` string, required: URL of the asset containing an attribution token - `alt` string, required: Alt text of the asset - `startDate` string, date-time, required: Beginning date of offer (UTC) - `expirationDate` string, date-time, required: Expiration date of offer if applicable (UTC) - `isTargeted` boolean, required: True returns only targeted offers, false returns only non-targeted offers - `minTransactionAmount` UsersRewardsAmount - `type` 'CENTS', required - `value` integer, required - `maxTransactionAmount` UsersRewardsAmount - `type` 'CENTS', required - `value` integer, required - `minRewardAmount` UsersRewardsAmount - `type` 'CENTS', required - `value` integer, required - `maxRewardAmount` UsersRewardsAmount - `type` 'CENTS', required - `value` integer, required - `websiteUrl` string: URL to the website of the offer provider - `description` string: Description of the offer - `components` CommonsOfferComponents: UI component data for rendering offer details - `shortDescription` string: Short description for the offer - `longDescription` string: Long description for the offer - `baseReward` string: Formatted reward string - `boostedReward` string: Formatted boosted reward string - `cta` CommonsCtaComponent: Call-to-action button component for offers - … - `tags` string[]: Tags for the offer - `detailTags` string[]: Detail tags for the offer - `logoFlare` CommonsLogoFlare: Logo flare configuration for offer display - … - `progressBar` CommonsProgressBar: Progress bar component for tracking offer redemption progress - … - `relationships` UsersRewardsEligibilityOfferRelationship - `category` UsersRewardsCategoryRelationship, required - `data` UsersRewardsCategoryData[], required - … - `locations` CommonsRelationshipMultiple - `data` CommonsRelationshipData[], required - … - UsersRewardsCategoryIncluded - `id` string, required: id of the category - `type` 'category', required - `attributes` UsersRewardsCategoryFields, required - `name` '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', required: Category of merchant. Please use URL Encode for non single word categories. (Food & Beverage should be Food%20%26%20Beverage) ## Other responses - `400`: Error response with status 400 - `401`: Error response with status 401 - `404`: Error response with status 404 - `429`: The issuer's traffic grew faster than its allowed rate, or the endpoint's own limit was reached. If the response includes a `Retry-After` header, wait that many seconds before retrying. See [Rate Limits](/2024-10-01/api/integration-guides/rate-limits). - `500`: Error response with status 500 ## Changes - **2026-10-22** `4e87fc8b018b`: 2 info - added the non-success response with the status `429` - added the optional property `included/items/oneOf[subschema #1: OfferDataUnion]/oneOf[subschema #1]/relationships/oneOf[subschema #1: CategoryRelationshipObject]/locations` to the response with the `200` status [Operation history](https://skmtc.dev/getkard/apis/getkard-2/changes/v2/issuers/:organizationId/users/:userId/locations/get.md) --- [API](https://skmtc.dev/getkard/apis/getkard-2.md) - [All operations](https://skmtc.dev/getkard/apis/getkard-2/llms.txt) - [OpenAPI document](https://skmtc.dev/getkard/apis/getkard-2/revisions/bd47764afa21?raw)