# Get nearby retailers

`GET /idp/v1/retailers`

Get a list of nearby retailers based on the specified postal code and country code.

## Authorization[​](#authorization "Direct link to Authorization")

| Name            | In     | Description                                                                    |
| --------------- | ------ | ------------------------------------------------------------------------------ |
| `Authorization` | header | The Authorization header with the bearer token acquired during authentication. |

## URL parameters[​](#url-parameters "Direct link to URL parameters")

| Name           | In    | Type   |                                Required                                | Description                                                                    |
| -------------- | ----- | ------ | :--------------------------------------------------------------------: | ------------------------------------------------------------------------------ |
| `postal_code`  | query | string | ![Required](/assets/ideal-img/required-icon.1609340.72.png "Required") | The US postal code. Used to find retailers in the vicinity of the postal code. |
| `country_code` | query | string | ![Required](/assets/ideal-img/required-icon.1609340.72.png "Required") | The country which the postal code belong to. Either 'US' or 'CA'.              |

## Request body[​](#request-body "Direct link to Request body")

None.

## Request examples[​](#request-examples "Direct link to Request examples")

* cURL
* Java
* Python
* Go
* Node.js

```
curl --request GET \

  --url 'https://connect.instacart.com/idp/v1/retailers?postal_code=string&country_code=string' \

  --header 'Accept: application/json' \

  --header 'Authorization: Bearer <token>'
```

```
HttpResponse<String> response = Unirest.get("https://connect.instacart.com/idp/v1/retailers?postal_code=string&country_code=string")

  .header("Accept", "application/json")

  .header("Authorization", "Bearer <token>")

  .asString();
```

```
import http.client



conn = http.client.HTTPSConnection("connect.instacart.com")



headers = {

    'Accept': "application/json",

    'Authorization': "Bearer <token>"

}



conn.request("GET", "/idp/v1/retailers?postal_code=string&country_code=string", headers=headers)



res = conn.getresponse()

data = res.read()



print(data.decode("utf-8"))
```

```
package main



import (

	"fmt"

	"net/http"

	"io"

)



func main() {



	url := "https://connect.instacart.com/idp/v1/retailers?postal_code=string&country_code=string"



	req, _ := http.NewRequest("GET", url, nil)



	req.Header.Add("Accept", "application/json")

	req.Header.Add("Authorization", "Bearer <token>")



	res, _ := http.DefaultClient.Do(req)



	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)



	fmt.Println(res)

	fmt.Println(string(body))



}
```

```
const http = require('https');



const options = {

  method: 'GET',

  hostname: 'connect.instacart.com',

  port: null,

  path: '/idp/v1/retailers?postal_code=string&country_code=string',

  headers: {

    Accept: 'application/json',

    Authorization: 'Bearer <token>'

  }

};



const req = http.request(options, function (res) {

  const chunks = [];



  res.on('data', function (chunk) {

    chunks.push(chunk);

  });



  res.on('end', function () {

    const body = Buffer.concat(chunks);

    console.log(body.toString());

  });

});



req.end();
```

## Response[​](#response "Direct link to Response")

| Field       | Type                                |                                Required                                | Description                    |
| ----------- | ----------------------------------- | :--------------------------------------------------------------------: | ------------------------------ |
| `retailers` | Array([Retailer](#Retailer-object)) | ![Optional](/assets/ideal-img/optional-icon.c3c3a0c.72.png "Optional") | The returned nearby retailers. |

###### Retailer Object[​](#Retailer-object "Direct link to Retailer-object")

| Field               | Type   |                                Required                                | Description                                                                                                           |
| ------------------- | ------ | :--------------------------------------------------------------------: | --------------------------------------------------------------------------------------------------------------------- |
| `retailer_key`      | string | ![Optional](/assets/ideal-img/optional-icon.c3c3a0c.72.png "Optional") | The unique identifier that represents a retailer as a whole organization, rather than individual stores or locations. |
| `name`              | string | ![Optional](/assets/ideal-img/optional-icon.c3c3a0c.72.png "Optional") | The retailer name.                                                                                                    |
| `retailer_logo_url` | string | ![Optional](/assets/ideal-img/optional-icon.c3c3a0c.72.png "Optional") | The retailer logo URL.                                                                                                |

## Response examples[​](#response-examples "Direct link to Response examples")

## 200 Success

* `200`
  <!-- -->
  Get nearby retailers successfully with valid US postal\_code
* `200`
  <!-- -->
  Get nearby retailers successfully with valid CA postal\_code

```
{

  "retailers": [

    {

      "retailer_key": "test-retailer",

      "name": "Test Retailer",

      "retailer_logo_url": "www.logoUrl.com"

    }

  ]

}
```

```
{

  "retailers": [

    {

      "retailer_key": "test-retailer",

      "name": "Test Retailer",

      "retailer_logo_url": "www.logoUrl.com"

    }

  ]

}
```

<!-- -->