Skip to content

Locations Management

There are two types of locations: - premises, where a linked customer record exists (regardless of the service being active or not) - predefined premises, which are predefined premise data that is preloaded prior to customer engagement

List Addresses

The API provides an endpoint do a search of physical addresses based on a given text pattern. This endpoint returns a limited number of addresses, to get more specific data, add more text to your search.

GET https://stage.provider-service.dev.aex.systems/locations

Request Parameters:

  • address (string, required): Text to filter known addresses by.

file_type_swagger Search Addresses

Example Response
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
[
  "1, Mzolo Street, Mohlakeng, Randfontein, 1759, Gauteng",
  "10, Mzolo Street, Mohlakeng, Randfontein, 1759, Gauteng",
  "10, Seme Street, Mohlakeng, Randfontein, 1759, Gauteng",
  "100, Dlamini Street, Mohlakeng, Randfontein, 1759, Gauteng",
  "1000, Thebenare Street, Mohlakeng, Randfontein, 1759, Gauteng",
  "1001, Thebenare Street, Mohlakeng, Randfontein, 1759, Gauteng",
  "100-11266, Darius Mhlongo St, Mohlakeng Ext 7, Randfontein, ZA, 1766, Gauteng",
  "1002, Thebenare Street, Mohlakeng, Randfontein, 1759, Gauteng",
  "1003, Thebenare Street, Mohlakeng, Randfontein, 1759, Gauteng",
  "1004, Thebenare Street, Mohlakeng, Randfontein, 1759, Gauteng"
]

NOTE This endpoint only returns a list of addresses, with no additional details about the location. To get additional details, use one of the endpoints described below.

The API provides an endpoint to search locations within a certain radius of a point on a map represented by its latitude & longitude. This is useful for cases where there is no reliable street address data.

NOTE This endpoint returns a paged list (with up to 10 items per page) of locations within a 500m radius of the latitude/longitude point provided.

POST https://stage.provider-service.dev.aex.systems/locations/proximity-search

file_type_swagger Create Service

Example Request
1
2
3
4
{
  "latitude": -26.20593,
  "longitude": 27.70701
}

Example Response
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
{
  "items": [
    {
      "predefinedPremiseId": "0e3b0d12-66fe-47f9-9323-5b0c1772938d",
      "address": "1497, Oranjerivier Street, Toekomsrus, Randfontein, 1759, Gauteng",
      "premiseId": null,
      "pointCoordinates": {
        "latitude": -26.2059594575,
        "longitude": 27.7068096909
      },
      "distanceInKilometers": 0.020250613672338807
    },
    {
      "predefinedPremiseId": "ce6fac08-56bc-4dde-a7a0-ab82c9d7e0e0",
      "address": "1496 (Cottage), Oranjerivier Street, Toekomsrus, Randfontein, ZA, 1759, Gauteng",
      "premiseId": null,
      "pointCoordinates": {
        "latitude": -26.2057499275,
        "longitude": 27.7067991369
      },
      "distanceInKilometers": 0.029042599154192907
    },
    {
      "predefinedPremiseId": "703d7af3-f5fa-4a3b-a8eb-3cd45de0205a",
      "address": "1496, Oranjerivier Street, Toekomsrus, Randfontein, 1759, Gauteng",
      "premiseId": null,
      "pointCoordinates": {
        "latitude": -26.2057499275,
        "longitude": 27.7067991369
      },
      "distanceInKilometers": 0.029042599154192907
    },
    {
      "predefinedPremiseId": "c524c2bb-14f8-40f5-95fe-16103798dd40",
      "address": "4, Plum Street, Toekomsrus, Randfontein, 1759, Gauteng",
      "premiseId": null,
      "pointCoordinates": {
        "latitude": -26.2060026147,
        "longitude": 27.7065857598
      },
      "distanceInKilometers": 0.04308776317946444
    },
    {
      "predefinedPremiseId": "02c4af94-8255-42f7-86aa-b980b585eb94",
      "address": "1495, Oranjerivier Street, Toekomsrus, Randfontein, 1759, Gauteng",
      "premiseId": null,
      "pointCoordinates": {
        "latitude": -26.2055769044,
        "longitude": 27.7067921121
      },
      "distanceInKilometers": 0.04487829619927441
    },
    {
      "predefinedPremiseId": "9722b89e-d4a0-4ead-90cc-f79a10a7f73a",
      "address": "2, Plum Street, Toekomsrus, Randfontein, 1759, Gauteng",
      "premiseId": null,
      "pointCoordinates": {
        "latitude": -26.2062469838,
        "longitude": 27.7066937684
      },
      "distanceInKilometers": 0.047304173707176475
    },
    {
      "predefinedPremiseId": "ec669338-a74b-4fa8-a5cb-5517c5add7da",
      "address": "4 (Cottage), Plum Street, Toekomsrus, Randfontein, ZA, 1765, Gauteng",
      "premiseId": null,
      "pointCoordinates": {
        "latitude": -26.2060119,
        "longitude": 27.7065113
      },
      "distanceInKilometers": 0.050579670067303795
    },
    {
      "predefinedPremiseId": "75f4f2a8-99ea-41f6-90b6-2b34ec8b964a",
      "address": "1500, Plum Street, Toekomsrus, Randfontein, 1759, Gauteng",
      "premiseId": null,
      "pointCoordinates": {
        "latitude": -26.2058047471,
        "longitude": 27.7065000838
      },
      "distanceInKilometers": 0.052744055752260134
    },
    {
      "predefinedPremiseId": "d310df32-7c3d-4d0e-b6ff-f7d4c6abead4",
      "address": "780 (Cottage), Visrivier Street, Toekomsrus, Randfontein, ZA, 1759, Gauteng",
      "premiseId": null,
      "pointCoordinates": {
        "latitude": -26.2059531695,
        "longitude": 27.707602262
      },
      "distanceInKilometers": 0.059143395353949066
    },
    {
      "predefinedPremiseId": "6e430669-efd9-4198-b7be-49a03cb8d3e4",
      "address": "780, Visrivier Street, Toekomsrus, Randfontein, 1759, Gauteng",
      "premiseId": null,
      "pointCoordinates": {
        "latitude": -26.2059531695,
        "longitude": 27.707602262
      },
      "distanceInKilometers": 0.059143395353949066
    }
  ],
  "page": 1,
  "count": 10,
  "total": 904
}

Get Location Details

The API provides an endpoint to retrieve the details of a given location, including whether the fiber is available in the location area and if the location is available for new service connection.

GET https://stage.provider-service.dev.aex.systems/details

Request Parameters:

  • address (string): The full address as it exists on the AEx platform
  • predefined_premise_id (uuid): The unique identifier of the predefined premise on the AEx platform

file_type_swagger Get Location Details

Example Response
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
  "predefinedPremiseId": "fefa6465-1c6f-4716-8d14-d685f89173cc",
  "address": "100-11266, Darius Mhlongo St, Mohlakeng Ext 7, Randfontein, ZA, 1766, Gauteng",
  "premiseId": "ef9ea474-b934-4461-a67e-de6e2bc3c7e4",
  "pointCoordinates": {
    "latitude": -26.222393,
    "longitude": 27.707889
  },
  "area": {
    "areaId": "2db9bf9b-85c9-4c8b-939c-3ffd8f20958b",
    "status": "Connected",
    "name": "Mohlakeng Cluster 15"
  },
  "existingService": null,
  "availability": {
    "status": true,
    "reason": "Cancelled Service"
  }
}

New Premise Creation

A new Premise record can be created using a predefined_premise_id, provided the given ID refers to an existing predefined premise record.

POST https://stage.provider-service.dev.aex.systems/locations/{predefined_premise_id}/premise

file_type_swagger Create Premise

A call to this endpoint will result in the creation of a new Premise record based on the attributes of the matching predefined premise.

Automation Exchange