Skip to content
FFicanex

Request 2

ReturnAtmSearchByAddress

Find ATMs near an address

GEThttps://api.ficanex.ca/service/json/ReturnAtmSearchByAddressRetrieves information. No data is changed.

Description

Returns the ATMs within a set distance of a street address, nearest first. THE EXCHANGE first converts the address into a map location (a latitude and longitude), then measures the distance from that point.

Use Case

Use this request to find ATMs near a street address, such as a member's home or office. For example, search within 5 kilometres of an address to list the closest ATMs.

The Request

GETReturnAtmSearchByAddress

https://api.ficanex.ca/service/json/ReturnAtmSearchByAddress?strAtmServiceKey=YOUR_KEY&strAddress=1620+Lonsdale+Avenue&strCity=North+Vancouver&bytRadius=5

operationparametervalueYOUR_KEY replace with your key+ is a spaceThe first parameter follows ?, and each additional parameter follows &.

The Response

ATMs Found

The address was located, and these ATMs are within the requested distance.

{  "count": 1,  "coordinates": { "latitude": 49.3380932, "longitude": -123.0692896 },  "locations": [    {      "index": 0,      "id": 2021,      "atmIdentifier": "VSCU5972",      "institution": {        "id": 303,        "name": "Vancity Credit Union",        "url": "",        "isAtlanticCreditUnion": 0      },      "coordinates": { "latitude": 49.3236, "longitude": -123.072 },      "address": {        "streetAddress": "1620 Lonsdale Avenue",        "city": "North Vancouver",        "province": "BC",        "postalCode": "V7M2J3",        "landmark": "Lonsdale & 17th Street"      },      "features": {        "deposits": 1,        "hours": 2,        "driveThru": 0,        "pinChange": 1,        "voiceGuidance": 1      },      "creditCards": { "visa": 1, "plus": 0, "mastercard": 0, "cirrus": 1 },      "languages": ["en", "fr"]    }  ]}

The Request

The parameters sent with the request. Parameters marked Required must be included. The Example tab shows the complete request.

Parameters

Each parameter is added to the end of the request address.

strAtmServiceKeystringRequired

The Web Service Key assigned to your Financial Institution. Required for every request.

Example YOUR_KEY

strAddressstringRequired

The street address to search near.

Example 1620 Lonsdale Avenue

bytRadiusnumberRequired

The search distance, in kilometres, measured from the location. Use 0 to search with no distance limit.

Example 5

strCitystringOptional

The city of the address. Used to locate the address accurately; it does not limit which ATMs are returned.

Example North Vancouver

strProvincestringOptional

The province of the address, such as BC. Used to locate the address accurately; it does not limit which ATMs are returned.

Example BC

strPostalCodestringOptional

The postal code of the address. Used to locate the address accurately.

Example V7M2J3

bShowDuplicateAddressesnumberOptional

Set to 1 to include ATMs that share the same street address, postal code and city. If left out, only one ATM per address is returned.

Possible values0one ATM per address1include ATMs that share an address

The Response

The information returned by the request. The Example tab shows each response in full.

Successful Response Fields

countnumber

The number of ATMs in the response. 0 means no ATMs were found.

Example 1

coordinatesobject

The location the search distance was measured from.

Example { "latitude": 49.3380932, "longitude": -123.0692896 }

locationsarray

The list of ATMs, nearest first. Each item is an ATM record.

Example [ ... ]

ATM Record Fields

Every ATM includes these fields. These are the JSON field names; JSON or XML? shows how XML writes them.

indexnumber

The ATM's position in the response, starting at 0.

Example 0

idnumber

The ATM's ID. Use it with ReturnAtm.

Example 2021

atmIdentifierstring

The ATM ID, as shown in the FI Portal.

Example VSCU5972

institution.idnumber

The ID of the Financial Institution the ATM belongs to.

Example 303

institution.namestring

The Financial Institution's name. Can be empty.

Example Vancity Credit Union

institution.urlstring

The Financial Institution's website address. Currently always empty.

Example ""

institution.isAtlanticCreditUnionnumber

1 if the Financial Institution is an Atlantic credit union, otherwise 0.

Possible values0No1Yes
coordinates.latitudenumber

The ATM's latitude. Use it to place the ATM on a map.

Example 49.3236

coordinates.longitudenumber

The ATM's longitude. Use it with the latitude to place the ATM on a map.

Example -123.072

address.streetAddressstring

The ATM's street address.

Example 1620 Lonsdale Avenue

address.citystring

The ATM's city.

Example North Vancouver

address.provincestring

The ATM's province.

Example BC

address.postalCodestring

The ATM's postal code, without a space.

Example V7M2J3

address.landmarkstring

A landmark to help find the ATM. If the ATM has none, the Financial Institution's default landmark text is used instead. Can be empty.

Example Lonsdale & 17th Street

features.depositsnumber

1 if the ATM accepts deposits, otherwise 0.

Possible values0No1Yes
features.hoursnumber

The ATM's opening hours, as a code.

Possible values1Business Hours Only224 Hours a Day3Restricted Access Building4Custom, see customHoursFrom and customHoursTo
features.customHoursFromstring

The opening time. Included only when hours is 4; otherwise this field is not included.

Example 09:00 AM

features.customHoursTostring

The closing time. Included only when hours is 4; otherwise this field is not included.

Example 05:00 PM

features.driveThrunumber

1 if the ATM is a drive-thru, otherwise 0.

Possible values0No1Yes
features.pinChangenumber

1 if members can change their PIN at the ATM, otherwise 0.

Possible values0No1Yes
features.voiceGuidancenumber

1 if the ATM offers voice guidance, otherwise 0.

Possible values0No1Yes
creditCards.visanumber

1 if the ATM accepts Visa.

Possible values0No1Yes
creditCards.mastercardnumber

1 if the ATM accepts Mastercard.

Possible values0No1Yes
creditCards.plusnumber

1 if the ATM accepts Plus.

Possible values0No1Yes
creditCards.cirrusnumber

1 if the ATM accepts Cirrus.

Possible values0No1Yes
languagesarray

The languages the ATM offers, as two-letter codes.

Possible valuesenEnglishfrFrenchzhChineseitItaliankoKoreanplPolishpaPunjabiesSpanishdeGermanptPortugueseruRussianjaJapanesearArabicviVietnamesetlTagalog

Possible Responses

Each response includes a Status CodeA standard code returned with every response to indicate the result of your request:200: Indicates success.400 & 404: Indicate a problem with the request format or a missing resource.500 & 502: Indicate an issue occurred on THE EXCHANGE server.. These match the tabs in The Response panel.

  • 200ATMs Found

    The address was located, and these ATMs are within the requested distance.

  • 200No ATMs Found

    The address was found, but no ATMs are within the requested distance. This is a successful response, not an error.

    What to do: Increase bytRadius to search a larger area.

  • 400Address Not Found

    THE EXCHANGE could not locate that address on the map.

    What to do: Check the spelling, and include strCity and strProvince. Only Canadian addresses are supported.

  • 400Missing strAddress

    The request did not include strAddress.

    What to do: Add strAddress to the request address.

  • 502Location Lookup Unavailable

    THE EXCHANGE could not reach the mapping service it uses to locate addresses and postal codes.

    What to do: This is an error in the web service, not in your request. Contact support@ficanex.ca.

  • 400Missing Web Service Key

    The request did not include strAtmServiceKey.

    What to do: Add strAtmServiceKey to the request address.

  • 400Invalid Web Service Key

    A key was sent, but it does not match any Financial Institution.

    What to do: Check the key for typing errors. Your current key is in the Overview section of your Financial Institution's page on the FI Portal.