Introduction

Base URL: http://tekoa.test

This documentation aims to provide all the information you need to work with our API.

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

Api Tokens can only be provided by a System Administrator. Please contact your administrator if you need an API token.

Basics

These endpoints provide basic information about address data by their keys.

GET api/cities/{key}

Example request:

$client = new \GuzzleHttp\Client();
$url = 'http://tekoa.test/api/cities/06027000';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

curl --request GET \
    --get "http://tekoa.test/api/cities/06027000" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "http://tekoa.test/api/cities/06027000"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

import requests
import json

url = 'http://tekoa.test/api/cities/06027000'
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (401):

Show headers

cache-control: no-cache, private
content-type: application/json
access-control-allow-origin: *


{
    "message": "Unauthorized"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

GET api/cities/{city_key}/districts/{key}

Example request:

$client = new \GuzzleHttp\Client();
$url = 'http://tekoa.test/api/cities/06027000/districts/001';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

curl --request GET \
    --get "http://tekoa.test/api/cities/06027000/districts/001" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "http://tekoa.test/api/cities/06027000/districts/001"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

import requests
import json

url = 'http://tekoa.test/api/cities/06027000/districts/001'
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (401):

Show headers

cache-control: no-cache, private
content-type: application/json
access-control-allow-origin: *


{
    "message": "Unauthorized"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

GET api/cities/{city_key}/zipAreas/{zip}

Example request:

$client = new \GuzzleHttp\Client();
$url = 'http://tekoa.test/api/cities/06027000/zipAreas/71001';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

curl --request GET \
    --get "http://tekoa.test/api/cities/06027000/zipAreas/71001" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "http://tekoa.test/api/cities/06027000/zipAreas/71001"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

import requests
import json

url = 'http://tekoa.test/api/cities/06027000/zipAreas/71001'
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (401):

Show headers

cache-control: no-cache, private
content-type: application/json
access-control-allow-origin: *


{
    "message": "Unauthorized"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

GET api/cities/{city_key}/zipAreas/{zipArea_zip}/streets/{key}

Example request:

$client = new \GuzzleHttp\Client();
$url = 'http://tekoa.test/api/cities/06027000/zipAreas/71001/streets/LINAB68369C';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

curl --request GET \
    --get "http://tekoa.test/api/cities/06027000/zipAreas/71001/streets/LINAB68369C" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "http://tekoa.test/api/cities/06027000/zipAreas/71001/streets/LINAB68369C"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

import requests
import json

url = 'http://tekoa.test/api/cities/06027000/zipAreas/71001/streets/LINAB68369C'
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

Example response (401):

Show headers

cache-control: no-cache, private
content-type: application/json
access-control-allow-origin: *


{
    "message": "Unauthorized"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/cities/{city_key}/zipAreas/{zipArea_zip}/streets/{key}

Headers

Content-Type

Example: application/json

Accept

Example: application/json

URL Parameters

city_key string

Example: 06027000

zipArea_zip string

Example: 71001

key string

Example: LINAB68369C

Utils

These endpoints are utility functions for fetching address-related data based on incomplete information, such as a zip code. They are designed to assist in address validation and auto-completion features in forms.

Checks if a given house number is valid for the street.

The house number is valid if it falls within the range of any of the street's house numbers and matches the parity (odd/even) of the type.

Example request:

$client = new \GuzzleHttp\Client();
$url = 'http://tekoa.test/api/utils/cities/06027000/zipAreas/71001/streets/LINAB68369C/numbers/check';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'number' => '123',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

curl --request POST \
    "http://tekoa.test/api/utils/cities/06027000/zipAreas/71001/streets/LINAB68369C/numbers/check" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"number\": \"123\"
}"

const url = new URL(
    "http://tekoa.test/api/utils/cities/06027000/zipAreas/71001/streets/LINAB68369C/numbers/check"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "number": "123"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

import requests
import json

url = 'http://tekoa.test/api/utils/cities/06027000/zipAreas/71001/streets/LINAB68369C/numbers/check'
payload = {
    "number": "123"
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/utils/cities/{city_key}/zipAreas/{zipArea_zip}/streets/{street_key}/numbers/check

Headers

Content-Type

Example: application/json

Accept

Example: application/json

URL Parameters

city_key string

Example: 06027000

zipArea_zip string

Example: 71001

street_key string

Example: LINAB68369C

Body Parameters

number string

The house number to check. Example: 123

Fetch zip areas for address suggestions

This endpoint is used to retrieve all relevant information for a given zip code, which can be used for address validation and auto-completion in forms. The response includes the zip area details, associated streets, postboxes, and city information. The data is cached for 24 hours to improve performance for frequently requested zip codes.

Example request:

$client = new \GuzzleHttp\Client();
$url = 'http://tekoa.test/api/utils/zip/architecto/areas';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'zipValue' => 'bngzm',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

curl --request GET \
    --get "http://tekoa.test/api/utils/zip/architecto/areas" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"zipValue\": \"bngzm\"
}"

const url = new URL(
    "http://tekoa.test/api/utils/zip/architecto/areas"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "zipValue": "bngzm"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

import requests
import json

url = 'http://tekoa.test/api/utils/zip/architecto/areas'
payload = {
    "zipValue": "bngzm"
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, json=payload)
response.json()

Example response (401):

Show headers

cache-control: no-cache, private
content-type: application/json
access-control-allow-origin: *


{
    "message": "Unauthorized"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.