Welcome to country-state-city microservice

Endpoint: Get State and Cities By Postal Code and Country Id

URL

GET https://api.country-state-city.rebuscando.info/public/getStateAndCitiesByPostalCodeAndCountryId?idcountry={idcountry}&postalcode={postalcode}

Description

This endpoint retrieves the state and cities information for a specified postal code and country ID.

Parameters

  • postalcode: The postal code to search for (string, required).
  • idcountry: The numeric identifier of the country (integer, required).

Response

  • Content-Type: application/json
  • HTTP Status Codes:
    • 200 OK: The request was successful, and the response body contains a JSON object with state and cities information.
    • 500 Internal Server Error: An error occurred on the server.

Response Body

The response body is a JSON object containing two fields: state and cities.

  • state: A state object with the following fields:
    • _id: Unique identifier for the state in the database (string)
    • id: Numeric identifier for the state (integer)
    • name: Name of the state (string)
    • country_id: Numeric identifier of the country (integer)
    • country_name: Name of the country (string)
    • country_code: ISO 3166-1 alpha-2 code of the country (string)
    • state_code: Code of the state (string)
    • latitude: Latitude coordinate of the state (float)
    • longitude: Longitude coordinate of the state (float)
    • prefix_postalcode: Postal code prefix for the state (string)
  • cities: An array of city objects, each with the following fields:
    • _id: Unique identifier for the city in the database (string)
    • id: Numeric identifier for the city (integer)
    • name: Name of the city (string)
    • state_id: Numeric identifier of the state (integer)
    • state_code: Code of the state (string)
    • state_name: Name of the state (string)
    • country_id: Numeric identifier of the country (integer)
    • country_code: ISO 3166-1 alpha-2 code of the country (string)
    • country_name: Name of the country (string)
    • latitude: Latitude coordinate of the city (float)
    • longitude: Longitude coordinate of the city (float)
    • wikiDataId: WikiData identifier for the city (string or null)
    • postalcodes: Array of postal codes for the city (array of strings)

Example Response

{
  "state": {
    "_id": "665d8ff2cba4c7b5eddab003",
    "id": 5101,
    "name": "Málaga",
    "country_id": 207,
    "country_name": "España",
    "country_code": "ES",
    "state_code": "MA",
    "latitude": 36.7182015,
    "longitude": -4.519306,
    "prefix_postalcode": "29"
  },
  "cities": [
    {
      "_id": "665d9055cba4c7b5eddc731a",
      "id": 35703,
      "name": "Málaga",
      "state_id": 5101,
      "state_code": "MA",
      "state_name": "Málaga",
      "country_id": 207,
      "country_code": "ES",
      "country_name": "España",
      "latitude": 36.72016,
      "longitude": -4.42034,
      "wikiDataId": "Q8851",
      "postalcodes": [
        "29001",
        "29002",
        "29003",
        "29004",
        "29005",
        "29006",
        "29007",
        "29008",
        "29009",
        "29010",
        "29011",
        "29012",
        "29013",
        "29014",
        "29015",
        "29016",
        "29017",
        "29018",
        "29140",
        "29190",
        "29191",
        "29193",
        "29196",
        "29197",
        "29590",
        "29591",
        "29620",
        "29720"
      ]
    },
    {
      "_id": "665d9055cba4c7b5eddc72fd",
      "id": 33898,
      "name": "Cártama",
      "state_id": 5101,
      "state_code": "MA",
      "state_name": "Málaga",
      "country_id": 207,
      "country_code": "ES",
      "country_name": "España",
      "latitude": 36.71068,
      "longitude": -4.63297,
      "wikiDataId": "Q935266",
      "postalcodes": [
        "29010",
        "29569",
        "29570",
        "29580",
        "29592"
      ]
    }
  ]
}

Error Response

If an internal server error occurs, the API will respond with a 500 Internal Server Error status code and an empty response body.