> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/returns-api/returns-api-v3.0/methods/location-methods.md).

# Location Methods

The following are the methods associated with the ‘Location’ API data type:

## GET- Get Drop-off Locations <a href="#get-get-drop-off-locations" id="get-get-drop-off-locations"></a>

This endpoint is used to retrieve PUDO Drop-off locations for a given carrier, based on the shoppers' postcode.

To get the drop-off locations send a `GET` request to `/location/`

### Method Parameters <a href="#method-parameters" id="method-parameters"></a>

<details>

<summary><strong>Request Parameters</strong></summary>

| **Field Name**        | **Data Type**                                            | **Required/Optional**   | **Description**                                                                                                                   |
| --------------------- | -------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| carrierServiceRouteId | string                                                   | Required                | <ul><li>This specifies the carrier to be used for PUDO.</li><li>CarrierServiceRouteId gathered from the return-methods.</li></ul> |
| countryCode           | <ul><li>string</li><li>Max 2 characters length</li></ul> | <p>Required<br><br></p> | Two letter country ISO.                                                                                                           |
| postCode              | string                                                   | Required                | Postcode based on which the locations will be searched.                                                                           |
| city                  | string                                                   |                         | City is used to further narrow down the search.                                                                                   |
| maxDistanceInKms      | integer                                                  |                         | <p>Maximum range of distance (km) around which the drop-off locations are gathered.</p><p>Default: 20km</p>                       |
| maxLocations          | integer                                                  |                         | <p>Maximum number of locations to return in the query.</p><p>Default: 10 locations</p>                                            |

</details>

<details>

<summary><strong>Response Parameters</strong></summary>

| **Field Name**          | **Type** | **Description**                                                         |
| ----------------------- | -------- | ----------------------------------------------------------------------- |
| locations               | array    | List of available locations based on the request parameters             |
| id                      | string   | The ID of the location                                                  |
| type                    | string   | <p>Location type - see enum/locationType</p><p><em>Store, PUDO</em></p> |
| name                    | string   | The name of the location.                                               |
| address1                | string   | The first line of the address of the location.                          |
| address2                | string   | The second line of the address of the location.                         |
| address3                | string   | The third line of the address of the location.                          |
| city                    | string   | The city for the location.                                              |
| postcode                | string   | The postcode for the location.                                          |
| sortcode                | string   | The sortcode for the location.                                          |
| region                  | string   | The region for the location.                                            |
| country                 | string   | The country for the location.                                           |
| telephone               | string   | The telephone number for the location.                                  |
| email                   | string   | The email contact for the location.                                     |
| longtitude              | double   | Location Longtitude (if available).                                     |
| latitude                | double   | Location Latitude (if available).                                       |
| distanceInKms           | double   | The distance to the location from the request postcode.                 |
| openingTimesDescription | string   | The description of the opening times at the location.                   |
| openingTimes            | array    | A list of opening times the location supports.                          |
| openingTimes.day        | string   | The Day of the provided opening time for the location.                  |
| openingTimes.opens      | string   | Display string for the opening time for the day.                        |
| openingTimes.closes     | string   | Display string for the closing time for the day.                        |
| carrierCode             | string   | Unique carrier code for ESW.                                            |
| carrierServiceRouteId   | string   | Unique reference for the associated ESW route.                          |

</details>

<details>

<summary>Response</summary>

| **Response Code** | **Description**                                          |
| ----------------- | -------------------------------------------------------- |
| 200 (Ok)          | The drop-off locations have been successfully retrieved. |

</details>

{% code title="Request-Response Example" expandable="true" %}

```json
{  // sample
  "locations": [{
     "id": "string",
     "type": "Store",
     "name": "string",
     "address1": "string",
     "address2": "string",
     "address3": "string",
     "city": "string",
     "postalCode": "string",
     "sortCode": "string",
     "region": "string",
     "countryCode": "string",
     "country": "string",
     "telephone": "string",
     "email": "string",
     "latitude": 0,
     "longitude": 0,
     "distanceInKms": 0,
     "openingTimesDescription": "string",
     "openingTimes": [{
       "day": "Sunday",
       "opens": "string",
       "closes": "string"
     }],
     "carrierCode": "string",
     "carrierServiceRouteId": "string"
  }]
}
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.esw.com/returns-api/returns-api-v3.0/methods/location-methods.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.