v1.0 Live

API Documentation — Autocomplete & Postal Codes

RO EN

1. Authentication & Security

Every request to the CeCodPostal API must include a secret API key, sent either in the X-API-KEY header or as an api_key query parameter. Keys can be generated from the B2B Dashboard.

How to send the API key:

Header (recommended): X-API-KEY: ccp_live_YOUR_API_KEY

URL query: https://cecodpostal.ro/api/v1/autocomplete?api_key=ccp_live_YOUR_API_KEY

GET /api/v1/autocomplete

2. Address Autocomplete & Smart Parsing

The algorithm parses raw strings typed by customers at checkout (e.g. Bucuresti Sector 2 Ciurea 14 or Constanta Mircea cel Batran 102) and extracts the city, street, odd/even number and the matching postal code.

Request Parameters (Query String)

Parameter	Type	Required	Description
q	String	Yes (min 2 chars)	Search text (may contain city, sector, street and number in a single field).
localitate	String	Optional	Filters strictly by city/sector.
judet	String	Optional	Filters by county.
numar	String/Int	Optional	Street or building number, used to match the exact number range.

curl -X GET "https://cecodpostal.ro/api/v1/autocomplete?q=Bucuresti%20Sector%202%20Ciurea%2014" \
     -H "X-API-KEY: YOUR_API_KEY"

$response = Http::withHeaders(['X-API-KEY' => 'YOUR_API_KEY'])
    ->get('https://cecodpostal.ro/api/v1/autocomplete', [
        'q' => 'Bucuresti Sector 2 Ciurea 14'
    ]);

$data = $response->json();

const response = await fetch('https://cecodpostal.ro/api/v1/autocomplete?q=Bucuresti%20Sector%202%20Ciurea%2014', {
    headers: {
        'X-API-KEY': 'YOUR_API_KEY'
    }
});
const data = await response.json();
console.log(data);

import requests

headers = {'X-API-KEY': 'YOUR_API_KEY'}
params = {'q': 'Bucuresti Sector 2 Ciurea 14'}

response = requests.get('https://cecodpostal.ro/api/v1/autocomplete', headers=headers, params=params)
data = response.json()

3. JSON Response Schema

Each item in the data array contains the information needed to autofill checkout fields:

JSON Field	Type	Description & Example
strada_complet	String	Street name together with the number range or exact number. E.g. "Strada Ciurea nr. 12-T"
cod_postal	String	Official 6-digit postal code. E.g. "021926"
localitate	String	City or sector name. E.g. "Sector 2" or "Constanta"
judet	String	County of the address. E.g. "Bucuresti" or "Constanta"

{
  "success": true,
  "count": 1,
  "data": [
    {
      "strada_complet": "Strada Ciurea nr. 12-T",
      "cod_postal": "021926",
      "localitate": "Sector 2",
      "judet": "Bucuresti"
    }
  ]
}

GET /api/v1/postcode/{code}

4. Strict Postal Code Lookup

Direct lookup by 6-digit postal code. Useful for autofilling the county and city when the customer only enters the code.

GET https://cecodpostal.ro/api/v1/postcode/021926
X-API-KEY: YOUR_API_KEY

5. Quick Integration: Drop-in JS Snippet

Add this script to your site or WooCommerce / custom checkout to enable autocomplete on the address field:

<!-- CeCodPostal.ro Autocomplete Snippet -->
<script>
  const CCP_API_KEY = 'ccp_live_YOUR_API_KEY';

  document.addEventListener('DOMContentLoaded', () => {
    const addressInput = document.querySelector('#billing_address_1') || document.querySelector('input[name="address"]');
    if (!addressInput) return;

    addressInput.addEventListener('input', async (e) => {
      const val = e.target.value;
      if (val.length < 3) return;

      try {
        const res = await fetch(`https://cecodpostal.ro/api/v1/autocomplete?q=${encodeURIComponent(val)}`, {
          headers: { 'X-API-KEY': CCP_API_KEY }
        });
        const data = await res.json();

        if (data.success && data.data.length > 0) {
          const item = data.data[0];
          // Autofill checkout fields
          if (document.querySelector('#billing_postcode')) {
            document.querySelector('#billing_postcode').value = item.cod_postal;
          }
        }
      } catch (err) {
        console.error('CCP Autocomplete Error:', err);
      }
    });
  });
</script>

6. Response Codes & HTTP Errors

HTTP Code	Meaning	Cause / Solution
200 OK	Success	The request was executed successfully.
401 Unauthorized	Missing key	You did not send the X-API-KEY header or the ?api_key= parameter.
403 Forbidden	Invalid key	The API key does not exist or the account is disabled.
404 Not Found	Code not found	No results for the requested postal code.
422 Unprocessable Entity	Invalid format	The postal code must contain exactly 6 digits.
429 Too Many Requests	Rate limit exceeded	You exceeded the request limit (60/minute or the monthly plan limit).