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 Create Location endpoint adds a new geographic entry — a province, state, or region — to the Ship Quote database. The adminFullCode is automatically derived from the countryCode and adminCode you supply (e.g. ES + 28 → ES-28), and a URL-safe normalizedName is generated from the name field. Province entries created here are subsequently resolvable via the List Provinces and Province by Postal Code endpoints, and their adminFullCode values are used directly as the province parameter in compareByProvinceCode.

​
Endpoint

POST /api/v1/locations

​
Request Body

​
countryCode
string
required
Two-letter ISO-3166-1 alpha-2 country code in uppercase. Examples: ES for Spain, FR for France, IT for Italy. Maximum 2 characters. The value is stored uppercased.
​
countryName
string
required
Full human-readable country name. Examples: España, France. Maximum 50 characters. The API normalises the value to Title Case on write (e.g. "españa" → "España").
​
adminCode
string
required
Administrative region code for the province, state, or region. This can be a numeric string (e.g. "28" for Madrid) or an alphabetic abbreviation (e.g. "VI" for Álava, "AB" for Albacete). Stored in uppercase. Together with countryCode this forms the adminFullCode, which is constructed automatically as countryCode + "-" + adminCode.
​
name
string
required
Display name of the province or region. Examples: Madrid, Álava, Albacete. Maximum 50 characters. A URL-safe lowercase normalizedName is derived automatically (accents stripped, spaces replaced with underscores).
​
type
string
Classification of the geographic entry. Accepted values: province, state, region. Defaults to province when omitted.

​
Response

A successful request returns HTTP 201 Created with the persisted location document in the response body.
​
id
string
MongoDB ObjectId of the newly created location document.
​
countryCode
string
Uppercased ISO-2 country code as stored (e.g. ES).
​
countryName
string
Title-cased country name as stored (e.g. España).
​
adminCode
string
Uppercased administrative region code (e.g. 28, VI).
​
adminFullCode
string
Fully-qualified code with country prefix, automatically constructed as countryCode + "-" + adminCode (e.g. ES-28, ES-VI). This is the value you pass as province to POST /rates/compareByProvinceCode.
​
name
string
Title-cased province name as stored (e.g. Madrid).
​
normalizedName
string
Auto-generated lowercase, accent-stripped, underscore-separated name used for internal indexing (e.g. madrid, alava).
​
postalCode
string
Two-digit postal prefix associated with this province (e.g. 28 for Madrid, 01 for Álava). This field is required by the model but is not part of the create request body — seed data sets it during bootstrap.
​
type
string
The stored entry type: province, state, or region.
​
createdAt
string
ISO 8601 timestamp of when the document was created.
​
updatedAt
string
ISO 8601 timestamp of the most recent update.

​
Examples

curl -X POST http://localhost:3000/api/v1/locations \
  -H "Content-Type: application/json" \
  -d '{
    "countryCode": "ES",
    "countryName": "España",
    "adminCode": "28",
    "name": "Madrid",
    "type": "province"
  }'

​
Error Responses

{
  "message": "Nombre de provincia obligatorio."
}
The adminFullCode field carries a unique index in MongoDB. If you attempt to create a second province with the same adminFullCode (e.g. ES-28), the API returns a 400 with a duplicate key error. Use List Provinces first to check whether a province already exists.
The Spanish province dataset is automatically seeded into the database on first startup. You only need this endpoint to add provinces from other countries or to extend the geographic coverage beyond the bundled seed data.

Build docs developers (and LLMs) love

Get started for freeTalk to us