Alternative Location Identifiers

This feature enhances our location data endpoints to help you map our stations and areas to your own system. By including a specific query parameter in your requests, you can receive a list of alternative identifiers (common aliases and external codes) for each location.

For example, Guarulhos Airport is the name set by Distribusion for the main station in the international airport of São Paulo in Brazil, but is also known as ‘São Paulo Airport’ or ‘Cumbica’. These other names of the station can be set as alternative identifiers and would appear in our endpoint responses to assist you with building a more robust mapping layer. This could allow your users to search with familiar terms, which your system can then translate into our specific codes for making API requests.

Requesting Alternative Identifiers

Alternative identifiers are not included in location responses by default. You must explicitly request them by adding the include[]=alternative_identifiers query parameter to your API call.

This feature is supported on the following endpoints: /stations, /stations/{station_code}, /areas and /cities.

When requesting alternative identifiers from /stations, /areas and /cities endpoints, you must also include pagination parameters:

• page[size]: The number of items to return per page.
• page[after]: The cursor for pagination e.g. station code to paginate after such as DEBERBB.

Sample Request for /stations

https://api.demo.distribusion.com/retailers/v4/stations/ATAADANG?locale=en&include[]=alternative_identifiers 

Response Structure

Including this parameter will add two new arrays to the attributes object of each location in the response:

• alternative_identifiers: Contains general, globally-recognized identifiers.
• carrier_alternative_identifiers: Contains identifiers specific to a particular carrier.

Sample Response from /stations/{station_code}

 
{
    "data": {
        "id": "ATAADANG",
        "type": "stations",
        "attributes": {
            "alternative_identifiers": [
                {
                    "value": "Angern an der March Train Station"
                }
            ],
            "code": "ATAADANG",
            "name": "Angern/March Train Station",
            "description": "",
            "station_type": "train_station",
            "street_and_number": "Bahnstraße 28",
            "zip_code": "2261",
            "time_zone": "Europe/Vienna",
            "uic_station_code": "8102819",
            "iata_airport_code": null,
            "longitude": 16.82591,
            "latitude": 48.38438
        },
        "relationships": {
            "city": {
                "data": {
                    "id": "ATAAD",
                    "type": "cities"
                }
            },
            "area": {
                "data": null
            }
        }
    },
    "jsonapi": {
        "version": "1.0"
    },
    "meta": {
        "locale": "en"
    },
    "included": [
        {
            "id": "ATAAD",
            "type": "cities",
            "attributes": {
                "code": "ATAAD",
                "name": "Angern an der March",
                "subdivision_code": null
            }
        }
    ]
}