Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/plantasur-dev/ship-quote/llms.txt

Use this file to discover all available pages before exploring further.

The Province by Postal Code endpoint resolves any valid Spanish postal code to the province it belongs to. Spanish postal codes are five digits long, and the first two digits uniquely identify the province — for example, any code beginning with 28 maps to Madrid and any code beginning with 23 maps to Jaén. Ship Quote uses this lookup internally inside POST /rates/compareByPostalCode to derive the province before querying rate tables, but the endpoint is also useful in your own UI for autocomplete flows: accept a partial postal code from the user, call this endpoint, and display the resolved province before the user submits the full shipping request.

​
Endpoint

GET /api/v1/locations/provincesByPostalCode/:postalCode

​
Path Parameters

​
postalCode
string
required
A five-digit Spanish postal code (e.g. 28001, 23700). Only the first two digits are used for the province lookup — 28001, 28080, and 28950 all resolve to Madrid. The API validates that the value is exactly five numeric digits; any other format returns a 400 error.Common Spanish province prefixes:
PrefixProvince
01Álava
02Albacete
08Barcelona
18Granada
23Jaén
28Madrid
41Sevilla
46Valencia

​
Response

Returns HTTP 200 OK with a single province object when a match is found.
​
id
string
MongoDB ObjectId of the province document.
​
countryCode
string
Uppercased ISO-2 country code. Always ES for the seeded dataset.
​
countryName
string
Country name as stored (e.g. Spain).
​
adminCode
string
Short administrative region code for the province (e.g. J for Jaén, M for Madrid).
​
adminFullCode
string
Fully-qualified province code (e.g. ES-J, ES-M). Pass this value as the province parameter when calling POST /rates/compareByProvinceCode.
​
name
string
Display name of the province (e.g. Jaén, Madrid).
​
normalizedName
string
Lowercase, accent-stripped version of the province name used for internal indexing (e.g. jaen, madrid).
​
postalCode
string
The two-digit prefix used as the lookup key (e.g. 23, 28).
​
type
string
Geographic classification. Always province for the Spanish seed data.
​
createdAt
string
ISO 8601 creation timestamp.
​
updatedAt
string
ISO 8601 last-updated timestamp.

​
Examples

curl -X GET "http://localhost:3000/api/v1/locations/provincesByPostalCode/28001"

​
Jaén response

{
  "id": "6a33f09ea7b22b51721309bc",
  "countryCode": "ES",
  "countryName": "Spain",
  "adminCode": "J",
  "adminFullCode": "ES-J",
  "name": "Jaén",
  "normalizedName": "jaen",
  "postalCode": "23",
  "type": "province",
  "createdAt": "2026-06-18T13:20:30.442Z",
  "updatedAt": "2026-06-18T13:20:30.442Z"
}

​
Madrid response

{
  "id": "6a33f09ea7b22b51721309d1",
  "countryCode": "ES",
  "countryName": "Spain",
  "adminCode": "M",
  "adminFullCode": "ES-M",
  "name": "Madrid",
  "normalizedName": "madrid",
  "postalCode": "28",
  "type": "province",
  "createdAt": "2026-06-18T13:20:30.436Z",
  "updatedAt": "2026-06-18T13:20:30.436Z"
}

​
Error Responses

{
  "message": "Incorrect Postal Code"
}
The postalCode parameter must be exactly 5 numeric digits. Passing a 2-digit prefix (28) or a non-numeric string returns 400 Bad Request. Always pass the full 5-digit postal code even though only the first two digits are used for the lookup.
Internally, getProvinceByPostalCode() slices the first two characters from the supplied code and performs an O(1) lookup against an in-memory Map that is populated at server boot. No MongoDB query is issued at request time, making this endpoint extremely fast even under high concurrency.
After calling this endpoint you have the province’s adminFullCode (e.g. ES-J). You can pass that directly to POST /rates/compareByProvinceCode along with the same postal code and your shipment items to get a full rate comparison — no second lookup needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us