# Post Code Lookup

The Post Code Lookup API provides developers with the ability to fetch information related to postal codes. This API offers three main functionalities:

* Fetching postal codes for a given latitude and longitude within a specified range
* Fetching latitude and longitude for a given postal code
* Fetching latitude and longitude for a partial postal code

## Fetch Postal Code for Latitude Longitude in a Given Range

Fetches the postal code for a specific location based on its latitude and longitude. The API can also return postal codes for locations within a specified distance range from the provided latitude and longitude. To get the postal code, you will need to call /geocode endpoint with the POST method.

### Request

#### Endpoint

`https://<host>/rest/s1/api/geocode`

#### Header

Content-Type:​ application/json

#### Body

```
{
  "json": {
    "params": {
      "q": "*:*",
      "fq": "{!geofilt sfield=location}",
      "pt": "18.180555,-66.749961",
      "d": "10"
    }
  }
}
```

| Parameter | Description                                             | Required (Y/N) |
| --------- | ------------------------------------------------------- | -------------- |
| `q`       | The query parameter                                     | N              |
| `fq`      | Applies a filter to the query search results            | N              |
| `pt`      | The latitude and longitude of the location              | N              |
| `d`       | The distance from which postal code needs to be fetched | N              |

Note:

* `pt` and `d` parameters are required to get the post codes
* `d` = 0 will fetch exact post code value for passed latitude and longitude
* `d` > 0 will fetch post codes within the given distance

### Response

#### Status Code

HTTP/1.1 200 OK

#### Headers

Content-Type: application/json

#### Body

```
{
  "responseHeader": {
    "status": 0,
    "QTime": 2,
    "params": {
      "json": "{\"params\":{\"q\":\"*:*\",\"fq\":\"{!geofilt-sfield=location}\",\"pt\":\"18.180555,-66.749961\",\"d\":\"10\"}}"
    }
  },
  "response": {
    "numFound": 1,
    "start": 0,
    "numFoundExact": true,
    "docs": [
      {
        "postcode": "601",
        "latitude": "18.180555",
        "longitude": "-66.749961",
        "country": "USA",
        "country-code-id": "601-USA",
        "location": "18.180555,-66.749961",
        "_version_": 1752733513051799552
      }
    ]
  }
}
```

| Parameter         | Description                                             |
| ----------------- | ------------------------------------------------------- |
| `numfound`        | The number of results found                             |
| `postcode`        | The postal code for the provided latitude and longitude |
| `latitude`        | The latitude of the postal code                         |
| `longitude`       | The longitude of the postal code                        |
| `country`         | The country of the provided postal code                 |
| `country-code-ID` | The country code ID of the provided country             |
| `location`        | The latitude and longitude points of the postal code    |

## Fetch latitude longitude for a postal code

Fetches the latitude longitude for a specific postal code. To look up the latitude longitude you will need to call the endpoint with the POST method.

### Request

#### Endpoint

`https://<host>/rest/s1/api/geocode`

#### Header

Content-Type:​ application/json

#### Body

```
{
  "json": {
    "query": "postcode:10001"
  }
}
```

| Parameter  | Description     | Required (Y/N) |
| ---------- | --------------- | -------------- |
| `postcode` | The postal code | Y              |

### Response

#### Status Code

HTTP/1.1 200 OK

#### Headers

Content-Type: application/json

#### Body

```
{
  "response": {
    "numFound": 1,
    "start": 0,
    "numFoundExact": true,
    "docs": [
      {
        "postcode": "10001",
        "latitude": "40.750636",
        "longitude": "-73.997177",
        "country": "USA",
        "countryCodeAlpha3": "USA",
        "countryCodeAlpha2": "US",
        "country-code-id": "10001-US",
        "location": "40.750636,-73.997177",
        "_version_": 1790686106947158016
      }
    ]
  }
}
```

| Parameter         | Description                                             |
| ----------------- | ------------------------------------------------------- |
| `postcode`        | The postal code for the provided latitude and longitude |
| `latitude`        | The latitude of the postal code                         |
| `longitude`       | The longitude of the postal code                        |
| `country`         | The country of the provided postal code                 |
| `country-code-id` | The country code ID of the provided country             |
| `location`        | The latitude and longitude points of the postal code    |

## Fetch latitude longitude for a partial postal code

Fetches the latitude longitude for a partial postal code. This API fetches all the latitude and longitude matching the partial postal code. To look up the latitude longitude for a partial postal code you will need to call the endpoint with the POST method.

### Request

#### Endpoint

`https://<host>/rest/s1/api/geocode`

#### Header

Content-Type:​ application/json

#### Body

```
{
  "json": {
    "query": "postcodelike:6011",
    "fields": ["latitude", "longitude"]
  }
}
```

| Parameter      | Description                                                                          | Required (Y/N) |
| -------------- | ------------------------------------------------------------------------------------ | -------------- |
| `postcodelike` | The partial postal code                                                              | Y              |
| `fields`       | The data fields or attributes that are included in the response body of the API call | Y              |

### Response

#### Status Code

HTTP/1.1 200 OK

#### Headers

Content-Type: application/json

#### Body

```
"response": {
 "numFound": 2,
 "start": 0,
 "numFoundExact": true,
 "docs": [
   {
     "latitude": "40.130099",
     "longitude": "-85.760763"
   },
   {
     "latitude": "32.754272",
     "longitude": "-97.083196"
   }
 ]
}
```

| Parameter   | Description                      |
| ----------- | -------------------------------- |
| `latitude`  | The latitude of the postal code  |
| `longitude` | The longitude of the postal code |


---

# Agent Instructions: 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:

```
GET https://docs.hotwax.co/documents/integrate-with-hotwax/hotwax-commerce-api-and-data-feeds/facility/postcode-lookup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.