.wpb_animate_when_almost_visible { opacity: 1; }
Discover 118712
Display residential and company contact details from the most enriched directory in France.
1.0

Getting started

Using the API

At first, the 118712 Directory API requires an access_token (based on OAuth 2.0 standard). This authentication method is described here.

An additional token, called 118712_API_Key, is mandatory. The 'X-118712-key' header must be used to carry out this token. This unique ID is provided by the 118712 team during API offer order/delivery process and is linked to your commercial contract and the application your created through Orange Partner developer portal.

The allowed traffic rate is 50 queries per second. Additional requests will be filtered by the network.

Some definitions

A subscriber represents any business or person that is present in the 118712 directory. Some subscribers (also known as MPL subscribers) have paid for better directory visibility, and will appear first in the results list.

A subscriber has standard data and possibly additional data:

  • Standard data is common directory information: name, phone number, address and such.
  • Additional data is more diverse information, generally relevant to some kinds of businesses : opening hours, user opinions, web links, etc.

Use cases

The GET /search/{query} operation allows you to perform different kind of search for subscribers:

  • Unique field search (query): plain old search based on a string, such as “restaurant saint malo” or “jean martin” or a phone number as “0142395710”.
  • Circular search: using a circle defined by WGS84 coordinates. The results are returned in distance order (from the nearest to the farthest from the centre of the search area).
  • Rectangular search: using a rectangle defined by a pair of WGS84 coordinates (top-left and bottom-right corners). The results are returned in distance order (from the nearest to the farthest from the centre of the search area).

Navigation between pages of results can only be done using the next or previous page.

Filters can be used to restrict the search so that results are relevant to your needs. For instance, the type of subscriber (i.e. professionals or individuals), the display of sponsored subscribers (aka MPL subscribers).

Links (URLs) to the 118712.fr website may also be returned.

curl -X GET \ -H "X-118712-key: {118712_API_Key}" \
     -H "Authorization: {authorization_header}" \
     -H "Accept: application/json" \
     https://api.orange.com/118712/directory/fr/v1/search/{query}?...

As an example: looking for restaurants in Saint-Malo city in France.

curl -X GET \ -H "X-118712-key: zk7bseqficp...7lan" \
     -H "Authorization: Bearer i6m2iIcY0S...ojAXXrH" \
     -H "Accept: application/json" \
     https://api.orange.com/118712/directory/fr/v1/search/restaurant-saint-malo

a/ If the transaction succeeds, you'll have the response to your search.

See item[] array of the 'SUBSCRIBERS' element for further details about search results. Additional results can be obtained using navigation links (see 'NAV' element).

{
    "INFO": {
        "searchTitle": "restaurant saint malo"
    },
    "NAV": {
        "currentPageNumber": 1,
        "previous": null,
        "next": "/search/restaurant-saint-malo?moredata=sxna..."
    },
    "SUBSCRIBERS": {
        "item": [
            {
                "name": "Restaurant, hôtel, bar l'équipe",
                "firstName": null,
                "lastName": null,
                "sponsored": "MPL",
                "type": "business",
                "activities": [
                    {
                        "code": "693780",
                        "label": "Restaurants",
                        "shortLabel": "Restaurant",
                        "type": "business"
                    }
                ],
                "ddpLink": null,
                "subscriberRef": "Bg4FZm3RX8QosjAGdwKYsVeHMAW9dC2yrVK9BHhzNLs.",
                "address": {
                    "street": "14 Avenue de Marville",
                    "loc": "SAINT MALO",
                    "zipcode": "35400",
                    "dept": "35",
                    "lat": "48.645726550661",
                    "lon": "-2.0068609714508",
                    "dist": null,
                    "phone": {
                        "info": "Restaurant",
                        "mode": "Main phone",
                        "number": "02 99 40 51 37",
                        "phoneRef": null
                    }
                },
                "additionalData": {
                    "medias": {
                        "providerName": "Visibilité par Orange",
                        "images": [
                            {
                                "url": "http://localmedia.fr/MP/40/25/40252.jpg",
                                "title": null,
                                "width": 120,
                                "height": 90
                            }
                        ],
                        "videos": [ ]
                    },
                    "commercialDescription": {
                        "providerName": "Visibilité par Orange",
                        "word": "Barl'équipe; RESTAURANT OUVRIER-FORMULE-SPEED A PARTIR 7.50 MENU 11.50\r\nPENSION-DEMI-PENSION-HOTEL PLEIN CENTRE\r\n50 M GARE TGV, POLE CULTUREL HIPPODROME,STADE,Tennis\r\nProximité plages ..."
                    },
                    "descriptionInformation": null,
                    "bookingInformation": null,
                    "programmingInformation": null,
                    "cinemaInformation": null,
                    "offers": null,
                    "providerReviews": [ ]
                }
            },
            {...}
        ]
    },
    "PROVIDERS": [
        {
            "name": "Visibilité par Orange",
            "picture": {
                "url": "http://c.annuaire.118712.fr/Icons/api_directory/logo_mpl.png",
                "width": 241,
                "height": 51
            }
        }
    ]
}

b/ If the transaction fails

Because you provide an invalid token for the X-118712-key header for example, you will get an error with JSON payload similar to:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
  "code": 1407,
  "message": "Access denied",
  "description": "You might not have access to the requested resource or operation."  
}

Get additional information from subscriberRef value

The GET /subscribers/{subscriber_id} operation allows you can obtain more informations (more images, opening hours, vacation information, prices, payments, menu, web site, email, all the phones) about a given subscription using the 'subscriberRef' value. This value is returned for each item within the 'SUBSCRIBERS' element of the search response, as shown in the previous use case:

curl -X GET \ -H "X-118712-key: {118712_API_Key}" \
     -H "Authorization: {authorization_header}" \
     -H "Accept: application/json" \
     https://api.orange.com/118712/directory/fr/v1/subscribers/{subscriber_id}

As an example:

curl -X GET \ -H "X-118712-key: zk7bseqficp...7lan" \
     -H "Authorization: Bearer i6m2iIcY0S...ojAXXrH" \
     -H "Accept: application/json" \
     https://api.orange.com/118712/directory/fr/v1/subscribers/Bg4FZm3RX8QosjAGdwKYsVeHMAW9dC2yrVK9BHhzNLs.

a/ If the transaction succeeds, you'll get more details about the subscriber.

{
    "SUBSCRIBER": {
        "name": "Restaurant, hôtel, bar l'équipe",
        "firstName": null,
        "lastName": null,
        "sponsored": "MPL",
        "type": "business",
        "activities": [
            {
                "code": "693780",
                "label": "Restaurants",
                "shortLabel": "Restaurant",
                "type": "business"
            }
        ],
        "address": {
            "street": "14 Avenue de Marville",
            "loc": "SAINT MALO",
            "zipcode": "35400",
            "dept": "35",
            "lat": "48.645726550661",
            "lon": "-2.0068609714508"
        },
        "phones": [
            {
                "info": "Restaurant",
                "mode": "Main phone",
                "number": "02 99 40 51 37",
                "phoneRef": null
            },
            {
                "info": "Réception",
                "mode": "Second phone",
                "number": "06 63 49 54 07",
                "phoneRef": null
            }
        ],
        "additionalData": {
            "medias": {
                "providerName": "Visibilité par Orange",
                "images": [
                    {
                        "url": "http://localmedia.fr/MP/40/25/40252.jpg",
                        "title": null,
                        "width": 120,
                        "height": 90
                    }
                ],
                "videos": [ ]
            },
            "commercialDescription": {
                "providerName": "Visibilité par Orange",
                "word": "Barl'équipe; RESTAURANT OUVRIER-FORMULE-SPEED A PARTIR 7.50 MENU 11.50\r\nPENSION-DEMI-PENSION-HOTEL PLEIN CENTRE\r\n50 M GARE TGV, POLE CULTUREL HIPPODROME,STADE,Tennis\r\nProximité plages ..."
            },
            "descriptionInformation": null,
            "bookingInformation": null,
            "programmingInformation": null,
            "cinemaInformation": null,
            "openingHours": {
                "providerName": "Visibilité par Orange",
                "items": [
                    {
                        "startDate": null,
                        "endDate": null,
                        "hours": "Lun - Ven: 09:30 21:30\nSam: 11:25 20:00\nDim: 08:30 14:30"
                    }
                ]
            },
            "vacationInformation": {
                "providerName": "Visibilité par Orange",
                "text": "du 20/08/2014 au 05/09/2014 et du 25/12/2014 au 28/12/2014"
            },
            "priceInformation": null,
            "paymentInformation": {
                "providerName": "Visibilité par Orange",
                "modes": "CB, Chèque, Ticket restaurant, Espèces"
            },
            "offers": null,
            "menu": null,
            "website": {
                "providerName": "Visibilité par Orange",
                "url": "http://www.hotel-restaurant-lequipe-st-malo.com",
                "label": null
            },
            "email": {
                "providerName": "Visibilité par Orange",
                "address": "equipe-bar@orange.fr"
            },
            "socialNetwork": null,
            "otherInformation": null,
            "providerReviews": [ ]
        }
    },
    "PROVIDERS": [
        {
            "name": "Visibilité par Orange",
            "picture": {
                "url": "http://c.annuaire.118712.fr/Icons/api_directory/logo_mpl.png",
                "width": 241,
                "height": 51
            }
        }
    ]
}

When the subscriber_id identifier doesn't match with a valid subscriber, a 200 OK HTTP status code is returned with the following response:

{
  "SUBSCRIBER": [],
  "PROVIDERS": []
}

b/ If the transaction fails because a captcha needs to be solved

The 'CAPTCHA' element is returned by the server with a captcha identifier and an URL to the captcha to be solved.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "INFO": {
    "searchTitle": null
  },
  "SUBSCRIBERS": {
    "item": []
  },
  "PROVIDERS": [],
  "CAPTCHA": {
    "id": "a1378c86d577b670d1cc3611544495229787ed86",
    "url": "http://captcha.orange.fr/index.php?data=NC0SCttUaMuaihIE%2Bx1k2NofC0j6yer7%2ByAH1BFmuvt9a4s%2F68%2BGP1FTLhZ9uzXVj5IKBwy7Pn04NtlJSO%2Bys%2B3Y0MRhAqlicOTXni91KLDUKxiADeY6MF7by8lNSx%2FsUqLtKEAuw3u7jfyyma2G9EaILtjz&iv=uqGiMhEPvEQmBeuDN0tSXsf1CL7aw8U2uS9cTn%2Bq24g%3D"
  }
}

b/ If the transaction fails due to other error cases

Because you provide an invalid device value (i.e. different than 'smartphone' , 'tablet', 'desktop' or 'tv') for example, you will get an error with JSON payload similar to:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "code": 1450,
  "message": "Invalid parameter value : device",
  "description": "With this parameter you should specify the client device, the device can be  'smartphone' , 'tablet', 'desktop'  or  'tv' "
}

Get audio code from phoneRef value

The POST /secretphones/{secretphone_id}/confidentialcode operation allows you to generate an audio code in order to call a subscriber who doesn't want to show his own phone number.

Each time this operation is called, a new audio code is generated.

curl -X POST \ -H "X-118712-key: {118712_API_Key}" \
     -H "Authorization: {authorization_header}" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \     
     https://api.orange.com/118712/directory/fr/v1/secretphones/{secretphone_id}/confidentialcode

As an example:

curl -X POST \ -H "X-118712-key: zk7bseqficp...7lan" \
     -H "Authorization: Bearer i6m2iIcY0S...ojAXXrH" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \     
     https://api.orange.com/118712/directory/fr/v1/secretphones/eEVeusEGecypNNi5OCvcTRgg-994Vf85/confidentialcode

a/ If the transaction succeeds, the IVR number and the confidential code are returned with pricing details.

{
  "IVRNumber": "0891700712",
  "confidentialCode": "57958",
  "price": "0.225 € TTC / MIN"
}

b/ If the transaction fails

Because you provide an invalid secretphone_id identifier for example, you will get an error with JSON payload similar to:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "code": 1440,
  "message": "Invalid parameter value : secretphone_id",
  "description": "The phoneRef is specified in the phone(s) section of Search or Subscribers resource"
}

Resolve a captcha

A captcha security mechanism has been implement to prevent from abnormal API usage. For instance, when a captcha needs to be solved when making a search, a CAPTCHA element is returned into the search response with a captcha identifier and a link to an image containing the expected characters.

The request to one the three previous operations needs to be done again with two additional query-string parameters:

  • captchaID: captcha identifier
  • captchaInput: the characters expected to solve the captcha
curl -X GET \ -H "X-118712-key: {118712_API_Key}" \
     -H "Authorization: {authorization_header}" \
     -H "Accept: application/json" \
     https://api.orange.com/118712/directory/fr/v1/{search_type}/{query}?captchaId={captchaID}&captchaInput={captchaInput}

As an example:

curl -X GET \ -H "X-118712-key: zk7bseqficp...7lan" \
     -H "Authorization: Bearer i6m2iIcY0S...ojAXXrH" \
     -H "Accept: application/json" \
     https://api.orange.com/118712/directory/fr/v1/search/restaurant-saint-malo?captchaId=56b43d4c21db497ec3a7445e3733a75234a26b66&captchaInput=JBNaFd

a/ If the transaction succeeds, you'll have the response of your search.

b/ if the transaction fails, you can have a new captcha to resolve or the following response if the captchaInput does not contain the number of expected characters.

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "code": 1430,
  "message": "Invalid parameter value: captchaInput",
  "description": "This parameter should be the content of the captcha"
}