Eligibility - API Documentation 1.0

Eligibility API Resources

Table of Contents

• Prerequisite authentication
• Base URL
• Resources
• Errors

Prerequisite authentication

API Key

The API requires an API-Key to access to it

• Your Orange Business representative will provide you this API key.
• The API key must be added to HTTP headers of each API call.
• It has to be put in the X-Api-Key header.
• The API requires also the generation of an API-Key. API-Key expires after 2 years and must be renewed by asking to Orange Support.

oAuth2

The access to this API is secured by the OAuth 2.0 framework with the Client Credentials grant type, which means that you will have to present an OAuth 2.0 access_token whenever you want to request this API.

It's easy to negotiate this access_token: just send a request to the proper token negotiation endpoint, with a Basic Authentication header valued with your own client_id and client_secret.

For this API, the token negotiation endpoint is:

https://api.orange.com/oauth/v3/token

A technical guide is available to learn how to negotiate and manage these access_token.

Important

• Please pay particular attention to properly handle authentication error responses in your application. See the section Errors
• The access_token default lifetime is 60 minutes.
• Header Accept: application/json is now required, when it’s omitted you will receive an error 406 error.

Base URL

The Base URL is the first part of the full invocation URL, just before the resource paths. Whenever you make requests on this API, you will need to prepend the following Base URL to the resource paths defined for this API.

If you request this API and encounter a 404 NOT FOUND HTTP error response, please check first that the Base URL is correct.

The Base URL for this API is:

https://api.orange.com/eligibility/b2b/v1/

Resources

A Point of Interest (POI) represents a geographic location that can either be an address or a building. Each POI contains information about the eligibility of Copper and Fiber supports.

To consume the API, you can follow these steps:

1 - Send a request with the fullTextAddress parameter:

• If there are matching POIs, you will receive a list of POIs corresponding to the provided address.
• If no matching address is found, you will receive an "Address not found" message.

2 - Send a request with the buildingCode parameter:

• If there is a matching POI, you will receive the POI corresponding to the provided building code.
• If no matching building code is found, you will receive a "Building not found" message.

3 - Send a request with both fullTextAddress and buildingName parameters:

• The API will search for the specified building name within the provided address.
• If a matching building is found, the API will retrieve the building code and calculate the eligibility, returning the corresponding POI.
• If no matching building is found, you will receive an appropriate error message.

Important

• The API takes into consideration the following inputs in the following order: buildingCode, fullTextAddress + buildingName, fullTextAddress.
• For FTTE support, eligibility calculations cannot be performed if an address contains more than five buildings. In such cases, the API will return a comment stating: "Eligibility calculation cannot be performed as the number of buildings exceeds 5." To retrieve FTTE eligibility information for a specific building, you should make a separate API request using the buildingCode parameter. This will provide you with the necessary eligibility information for the building in question.
• A fullTextAddress should have the street and city information separated by a comma. For example, "340 Avenue De La Marne, 59700 Marcq En Baroeul" would be a correctly formatted fullTextAddress.

By following these guidelines, you can effectively use the API to retrieve eligibility information for various Points of Interest.

URL

Parameters:

• fullTextAddress: The full text address to search for
• buildingName: The building name
• buildingCode: The building code

Output

Example:

GET /poi?fullTextAddress=14%20Rue%20Maurice%20Choury,%2020000%20Ajaccio HTTP/1.1

[
    {
        "id": "OC43MjgxNTk1MDE5MTUxNjM0MS45MTk0MTEyNzQzMzQzMw==",
        "building": {
            "id": "IMB/2A004/C/01RJ"
        },
        "geoCoding": {
            "longitude": 8.728159501915163,
            "latitude": 41.91941127433433
        },
        "formattedAddress": "RUE MAURICE CHOURY, 20000 AJACCIO",
        "address": {
            "cityCode": "2A004",
            "postalCode": "20000",
            "rivoliCode": "0903"
        },
        "supports": {
            "fiber": {
                "ftte": {
                    "status": "eligible",
                    "properties": {
                        "isOptimalAvailable": true
                    },
                    "comments": [
                        "FibreSmart: partiallyDeployed",
                        "FibreSmart Optimal: partiallyDeployed"
                    ]
                },
                "ftth": {
                    "status": "eligible"
                },
                "ftto": {
                    "status": "eligible",
                    "properties": {
                        "isFiberAvailable": false,
                        "zoning": "ZONE1"
                    }
                }
            },
            "copper": {
                "adsl": {
                    "status": "eligible",
                    "properties": {
                        "bandwidth": 18,
                        "unit": "Mbits/s",
                        "countCopperPair": 8
                    }
                },
                "sdsl": {
                    "status": "eligible",
                    "properties": {
                        "bandwidth": 8,
                        "unit": "Mbits/s",
                        "countCopperPair": 8,
                        "countRequiredPairs": 4
                    }
                }
            }
        },
        "createdAt": "2023-04-07T10:32:10",
        "updatedAt": "2023-04-07T10:32:10"
    },
    {
        "id": "OC43MjgzNzc4NzY1NzM3MDg0MS45MTg1NjY5NzQ0NDMyMg==",
        "building": {
            "id": "IMB/2A004/X/03OL"
        },
        "geoCoding": {
            "longitude": 8.728377876573708,
            "latitude": 41.91856697444322
        },
        "formattedAddress": "RUE MAURICE CHOURY, 20000 AJACCIO",
        "address": {
            "cityCode": "2A004",
            "postalCode": "20000",
            "rivoliCode": "0903"
        },
        "supports": {
            "fiber": {
                "ftte": {
                    "status": "eligible",
                    "properties": {
                        "isOptimalAvailable": true
                    },
                    "comments": [
                        "FibreSmart: partiallyDeployed",
                        "FibreSmart Optimal: partiallyDeployed"
                    ]
                },
                "ftth": {
                    "status": "eligible"
                },
                "ftto": {
                    "status": "eligible",
                    "properties": {
                        "isFiberAvailable": false,
                        "zoning": "ZONE1"
                    }
                }
            },
            "copper": {
                "adsl": {
                    "status": "eligible",
                    "properties": {
                        "bandwidth": 18,
                        "unit": "Mbits/s",
                        "countCopperPair": 8
                    }
                },
                "sdsl": {
                    "status": "eligible",
                    "properties": {
                        "bandwidth": 8,
                        "unit": "Mbits/s",
                        "countCopperPair": 8,
                        "countRequiredPairs": 4
                    }
                }
            }
        },
        "createdAt": "2023-04-07T10:32:10",
        "updatedAt": "2023-04-07T10:32:10"
    },
    {
        "id": "OC43MjgyMzY0ODczMDkyODc0MS45MTg3MjkzNDA0ODg3NzQ=",
        "building": {
            "id": "IMB/2A004/X/048L"
        },
        "geoCoding": {
            "longitude": 8.728236487309287,
            "latitude": 41.918729340488774
        },
        "formattedAddress": "RUE MAURICE CHOURY, 20000 AJACCIO",
        "address": {
            "cityCode": "2A004",
            "postalCode": "20000",
            "rivoliCode": "0903"
        },
        "supports": {
            "fiber": {
                "ftte": {
                    "status": "eligible",
                    "properties": {
                        "isOptimalAvailable": true
                    },
                    "comments": [
                        "FibreSmart: partiallyDeployed",
                        "FibreSmart Optimal: partiallyDeployed"
                    ]
                },
                "ftth": {
                    "status": "eligible"
                },
                "ftto": {
                    "status": "eligible",
                    "properties": {
                        "isFiberAvailable": false,
                        "zoning": "ZONE1"
                    }
                }
            },
            "copper": {
                "adsl": {
                    "status": "eligible",
                    "properties": {
                        "bandwidth": 18,
                        "unit": "Mbits/s",
                        "countCopperPair": 8
                    }
                },
                "sdsl": {
                    "status": "eligible",
                    "properties": {
                        "bandwidth": 8,
                        "unit": "Mbits/s",
                        "countCopperPair": 8,
                        "countRequiredPairs": 4
                    }
                }
            }
        },
        "createdAt": "2023-04-07T10:32:10",
        "updatedAt": "2023-04-07T10:32:10"
    },
    {
        "id": "NDEuOTE5MDIyNDEuOTE5MDIy",
        "geoCoding": {
            "longitude": 8.72814,
            "latitude": 41.919022
        },
        "formattedAddress": "RUE MAURICE CHOURY, 20000 AJACCIO",
        "address": {
            "cityCode": "2A004",
            "postalCode": "20000",
            "rivoliCode": "0903"
        },
        "supports": {
            "fiber": {
                "ftto": {
                    "status": "eligible",
                    "properties": {
                        "isFiberAvailable": false,
                        "zoning": "ZONE1"
                    }
                }
            },
            "copper": {
                "adsl": {
                    "status": "eligible",
                    "properties": {
                        "bandwidth": 18,
                        "unit": "Mbits/s",
                        "countCopperPair": 8
                    }
                },
                "sdsl": {
                    "status": "eligible",
                    "properties": {
                        "bandwidth": 8,
                        "unit": "Mbits/s",
                        "countCopperPair": 8,
                        "countRequiredPairs": 4
                    }
                }
            }
        },
        "createdAt": "2023-04-07T10:32:10",
        "updatedAt": "2023-04-07T10:32:10"
    }
]

GET /poi?buildingCode=IMB/59378/X/013S HTTP/1.1

[
    {
        "id": "My4xMTcxNzM3MTE1OTExNzUwLjY3NTg4MDQ0NjEwODAy",
        "building": {
            "id": "IMB/59378/X/013S"
        },
        "geoCoding": {
            "longitude": 3.11717371159117,
            "latitude": 50.67588044610802
        },
        "address": {
            "cityCode": "59378",
            "streetNumber": "340"
        },
        "supports": {
            "fiber": {
                "ftte": {
                    "status": "eligible",
                    "properties": {
                        "isOptimalAvailable": true
                    },
                    "comments": [
                        "FibreSmart: partiallyDeployed",
                        "FibreSmart Optimal: partiallyDeployed"
                    ]
                },
                "ftth": {
                    "status": "eligible"
                },
                "ftto": {
                    "status": "eligible",
                    "properties": {
                        "isFiberAvailable": false,
                        "zoning": "ZONE1"
                    }
                }
            },
            "copper": {
                "adsl": {
                    "status": "eligible",
                    "properties": {
                        "bandwidth": 1,
                        "unit": "Mbits/s",
                        "countCopperPair": 9
                    }
                },
                "sdsl": {
                    "status": "eligible",
                    "properties": {
                        "bandwidth": 2,
                        "unit": "Mbits/s",
                        "countCopperPair": 9,
                        "countRequiredPairs": 4
                    }
                }
            }
        },
        "createdAt": "2023-04-20T10:45:14",
        "updatedAt": "2023-04-20T10:45:14"
    }
]

GET /poi?fullTextAddress=340 Avenue De La Marne, 59700 Marcq En Baroeul&buildingName=A13 HTTP/1.1

[
    {
        "id": "My4xMTYxODU5NjA4OTQyODU3NTAuNjc1MTgxODE4MDAxNTI=",
        "building": {
            "id": "IMB/59378/X/013U",
            "name": "A13"
        },
        "geoCoding": {
            "longitude": 3.1161859608942857,
            "latitude": 50.67518181800152
        },
        "address": {
            "cityCode": "59378",
            "streetNumber": "340"
        },
        "supports": {
            "fiber": {
                "ftte": {
                    "status": "eligible",
                    "properties": {
                        "isOptimalAvailable": true
                    },
                    "comments": [
                        "FibreSmart: partiallyDeployed",
                        "FibreSmart Optimal: partiallyDeployed"
                    ]
                },
                "ftth": {
                    "status": "eligible"
                },
                "ftto": {
                    "status": "eligible",
                    "properties": {
                        "isFiberAvailable": false,
                        "zoning": "ZONE1"
                    }
                }
            },
            "copper": {
                "adsl": {
                    "status": "eligible",
                    "properties": {
                        "bandwidth": 1,
                        "unit": "Mbits/s",
                        "countCopperPair": 9
                    }
                },
                "sdsl": {
                    "status": "eligible",
                    "properties": {
                        "bandwidth": 2,
                        "unit": "Mbits/s",
                        "countCopperPair": 9,
                        "countRequiredPairs": 4
                    }
                }
            }
        },
        "createdAt": "2023-04-20T10:52:00",
        "updatedAt": "2023-04-20T10:52:00"
    }
]

Errors

Errors 401

If you get a status code 401 with the error code 42 (such as below), then request a new access_token.

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
  "code": 42,
  "message": "Expired credentials",
  "description": "The requested service needs credentials, and the ones provided were out-of-date."
}

Important

• Each access_token has a lifetime validity period (60 minutes by default). This validity period may change overtime to comply with security rules.
• Token requests are limited to 50 requests per minutes, when the rate limit is exceeded you will receive an error 429. Therefore, DON'T request an access_token each time you invoke the service API. DON'T hard-code a validity duration in your application. Instead, your application must parse the returned status code and error code to check if it needs to request a new access_token.

For other 401 errors: check that you provide the right Autorization header with the right Bearer.

Errors 400

In case of invalid request to the API, you will receive a 400 error code with detailed information in the body message, such as:

HTTP/1.1 400 Bad Request
{
    "code": 400100,
    "message": "malformatted value",
    "description": "the fullTextAddress value is malformatted, please use ',' to separate the street and the city informations"
}

HTTP/1.1 400 Bad Request
{
    "code": 40024,
    "message": "Invalid body field",
    "description": buildingCode must respect the following pattern: 'IMB/[A-Z0-9]{5}/[A-Z]{1}/[A-Za-z0-9]{4}'"
}

Errors 404

HTTP/1.1 404 Not Found
{
    "code": 4041,
    "message": "address not found",
    "description": "address unknown, please provide more information or contact an Orange advisor",
}

HTTP/1.1 404 Not Found
{
    "code": 4042,
    "message": "unknown building",
    "description": "unknown building, please provide more information or contact an Orange advisor",
}

Errors 503

HTTP/1.1 503 Service Unavailable
{
    "code": 2600,
    "message": "The service is temporarily unavailable",
    "description": "Source backend service is temporarily unavailable, please try again later."
}

Errors 500

HTTP/1.1 500 Internal Server Error
{
      "code": 1,
      "message": "Internal error",
      "description": "Generic failure message, used if no more precise code can be provided."
}

Consult all generic errors.