Nedese API

Modern RESTful API providing access to country, state, and city information

https://api.nedese.com/api/location/v1

Introduction

Nedese API provides programmatic access to country, state, and city information worldwide.

Currently closed for external use. For more information, contact info@nedese.com.

Features

Comprehensive country, state, and city database
RESTful API design
JSON format responses
Secure authentication system

Request Format

All API requests must include the following headers:

Content-Type: application/json
Accept: application/json

Authentication

Three authentication headers are required to access the API.

Required Headers

Header	Description
`API-ID`	Your unique API ID number
`API-KEY`	Your API access key
`API-SECRET`	Your API secret key

Example Request

curl -X GET https://api.nedese.com/api/location/v1/countries \
  -H "API-ID: your_api_id" \
  -H "API-KEY: your_api_key" \
  -H "API-SECRET: your_api_secret"

Countries

Endpoints used to retrieve information about countries worldwide.

All Countries

GET /countries

Returns a list of all registered countries in the system.

Request Example

curl -X GET https://api.nedese.com/api/location/v1/countries \
  -H "API-ID: your_api_id" \
  -H "API-KEY: your_api_key" \
  -H "API-SECRET: your_api_secret"

Response Example

[
  {
    "id": 1,
    "name": "Türkiye",
    "code": "TR",
    "phone_code": "+90",
    "currency": "TRY"
  },
  {
    "id": 2,
    "name": "United States",
    "code": "US",
    "phone_code": "+1",
    "currency": "USD"
  }
]

Single Country by Name

GET /countries/{name}

Returns information for the country with the specified **name**.

Parameter	Description
`name`	The unique name of the country (e.g., "Türkiye", "United States")

Request Example

curl -X GET https://api.nedese.com/api/location/v1/countries/Türkiye \
  -H "API-ID: your_api_id" \
  -H "API-KEY: your_api_key" \
  -H "API-SECRET: your_api_secret"

Response Example

{
  "id": 1,
  "name": "Türkiye",
  "code": "TR",
  "phone_code": "+90",
  "currency": "TRY"
}

States

Endpoints used to retrieve state information for countries.

States by Country Name

GET /countries/{countryName}/states

Returns all states belonging to the specified **country name**.

Parameter	Description
`countryName`	The unique name of the country (e.g., "Türkiye", "United States")

Request Example

curl -X GET https://api.nedese.com/api/location/v1/countries/Türkiye/states \
  -H "API-ID: your_api_id" \
  -H "API-KEY: your_api_key" \
  -H "API-SECRET: your_api_secret"

Response Example

[
  {
    "id": 1,
    "country_id": 1,
    "name": "İstanbul",
    "code": "34"
  },
  {
    "id": 2,
    "country_id": 1,
    "name": "Ankara",
    "code": "06"
  }
]

Single State by Name

GET /states/{name}

Returns information for the state with the specified **name**.

Parameter	Description
`name`	The unique name of the state (e.g., "İstanbul", "California")

Request Example

curl -X GET https://api.nedese.com/api/location/v1/states/İstanbul \
  -H "API-ID: your_api_id" \
  -H "API-KEY: your_api_key" \
  -H "API-SECRET: your_api_secret"

Response Example

{
  "id": 1,
  "country_id": 1,
  "name": "İstanbul",
  "code": "34"
}

Cities

Endpoints used to retrieve city information for states.

Cities by State Name

GET /states/{stateName}/cities

Returns all cities belonging to the specified **state name**.

Parameter	Description
`stateName`	The unique name of the state (e.g., "İstanbul", "California")

Request Example

curl -X GET https://api.nedese.com/api/location/v1/states/İstanbul/cities \
  -H "API-ID: your_api_id" \
  -H "API-KEY: your_api_key" \
  -H "API-SECRET: your_api_secret"

Response Example

[
  {
    "id": 1,
    "state_id": 1,
    "name": "Kadıköy",
    "postal_code": "34700"
  },
  {
    "id": 2,
    "state_id": 1,
    "name": "Beşiktaş",
    "postal_code": "34357"
  }
]

Single City by Name

GET /cities/{name}

Returns information for the city with the specified **name**.

Parameter	Description
`name`	The unique name of the city (e.g., "Kadıköy", "Los Angeles")

Request Example

curl -X GET https://api.nedese.com/api/location/v1/cities/Kadıköy \
  -H "API-ID: your_api_id" \
  -H "API-KEY: your_api_key" \
  -H "API-SECRET: your_api_secret"

Response Example

{
  "id": 1,
  "state_id": 1,
  "name": "Kadıköy",
  "postal_code": "34700"
}

Error Codes

Error codes and their descriptions that can be returned by the API.

Error List

Code	HTTP	Description
`1001`	401	Invalid API key
`1002`	401	Invalid API secret key
`1003`	401	Invalid API ID
`2001`	404	Country not found
`2002`	404	State not found
`2003`	404	City not found

Error Response Format

{
  "success": false,
  "error": {
    "code": 1001,
    "message": "Invalid API key"
  }
}