Discover_Image ATM Locator > Documentation

Overview


The ATM Locator Service provides the ATM Locations based on the location info.

Authentication-Making the first API request is only few steps away


  1. All projects start in Sandbox mode. Once you’re invited to gain access to this API you can login here to get Client Application ID (API Key) Client Application Secret, Consumer Application Certificate and API Plan name.

  2. All API requests must be authenticated with an OAuth token. To get the OAuth token, follow these simple steps

    1. Make a HTTP POST request to the endpoint /auth/oauth/v2/token with HTTP Authorization Header as Basic base64encoded(client_application_id:client_application_secret), Content-Type as application/x-www-form-urlencoded and Cache-Control as no-cache

    2. The response would contain an OAuth token along with token type and token expiry in seconds

      SAMPLE OAUTH TOKEN REQUEST

      POST /auth/oauth/v2/token?grant_type=xyz&scope=RWDS_xyz HTTP/1.1
      Authorization: sdlfsdf0dskladfk123456
      Content-Type: application/x-www-form-urlencoded
      Cache-Control: no-cache

      SAMPLE RESPONSE

      Response-Status: HTTP/1.1 200 OK
      Cache-Control: no-store
      Content-Type: application/json;charset=UTF-8
      Pragma: no-cache
      {
      "access_token": "sdlfsdf0dskladfk123456"
      "token_type": "xyz"
      "expires_in": 3600
      "scope": "RWDS_xyz"
      }

  3. Once an OAuth token is obtained, you can use the token along with Consumer Application Secret and API Plan name provided during Sandbox access in the HTTP Header of an API to make your first call. The same OAuth can be used for multiple API calls as long as it is not expired.

Access Error


User authentication failed with error code 1001 and HTTP Status Code as 401

Not authorized to access the resource! With the error code 1003 and HTTP Status Code as 403

Unsupported Media Type with HTTP status Code 415

API Structure


A typical API request would contain the sections HTTP Header, Request Header, Request Body as part of the request and HTTP Header, Response Header and Response Body as part of the response with some exception due to the nature of the API. Refer the individual end points to know more.

HTTP Header


We follow a robust standard for HTTP Header which includes the following parameters to be supplied while you are making an API request

Accept
Content-Type
Authorization
X-DFS-API-PLAN
The value for Authorization will be Basic access_token
The value for X-DFS-API-PLAN will be provided during App registration in the portal
Our HTTP Header in the response will include Access, Content-Type and Cache-Control

HTTP Status Codes


The HTTP Status Code returned in the response follows an industry API standard and designed to help you better interpret the underlying error.
User authentication failed with error code 1001 and HTTP Status as 401
Not authorized to access the resource! With the error code 1003 and HTTP Status as 403
Unsupported Media Type with HTTP status as 415
Validation error with the error code 10001 and HTTP Status as 400
Internal server error with the error code 10002 and HTTP Status as 500

dci/atm/v1/locations

/dci/atm/v1/locations


This API provides List of ATM’s based on the provided location info.

REQUEST ARGUMENTS


maxresults: string | optional

Maximum number of results required to be obtained as response

longitude: string | mandatory

Longitude of the location

latitude: string | mandatory

Latitude of the location

view: string | optional

ASurcharge or no Surcharge

radius: string | mandatory

Results within how many miles

REQUEST HTTP HEADERS


Authorization:

The value of the header is Bearer access_token

X-DFS-API-PLAN:

Name of the API plan assigned to the app during registration approval (e.g. DCI_ATM _PROD, DCI_ATM _SANDBOX)

SAMPLE CURL REQUEST

curl -X GET \
/dci/atm/v1/locations\ longitude=87.641206&latitude=41.884315&radius=1.000000 \
-H 'authorization: access_token ' \
-H 'cache-control: no-cache' \
-H 'x-dfs-api-plan: API_PLAN_NAME '

RESPONSE VALUES


id: string

ATM ID

latitude: float

ATM Location latitude

longitude: float

ATM Location longitude

name: string

Name of the ATM

features: SURCHARGE_FREE: string

Boolean to check if its free or not free

features: RESTRICTED: string

Does it have any Restricted access

features: BRAILLE: string

Does it access to people who lost their vision

features: DRIVE_UP: string

Will there be a drive up

features: WALK_UP: string

Or just walkable

address: Street_address: string

Address of the ATM

address: locality: string

City where the ATM is located.

address: region: string

State where ATM is located.

address: postalCode: string

Zipcode of the location.

address: country: string

Country where ATM is located.

address: formatted: string

Formatted Address of the ATM

address: homeaddress: string

Address

address: preferred: string

Is it preferred

preferred: string

Is it preferred

homeaddress: string

Address

Sample Response

HTTP 200
{
"id" : "3289632",

"latitude" : 41.880705,

"longitude" : -87.642473,

"name" : "WAL-MART",

"features" : {
"SURCHARGE_FREE": "YES",
"RESTRICTED": "UNKNOWN",
"BRAILLE": "UNKNOWN",
"DRIVE_UP": "UNKNOWN",
"WALK_UP": "NO",
},

"address" : {
"streetAddress": "570 W MONROE ST",
"locality": "CHICAGO",
"region": "IL",
"postalCode": "60661",
"country": "USA",
"formatted": "570 W MONROE ST\nCHICAGO, IL 60661\nUSA",
"homeAddress": "false",
"preferred": "false",
},

"preferred" : "false",

"homeAddress" : "false",
}

dci/atm/v1/healthcheck

/dci/atm/v1/healthcheck


This API can be used to check if the service is up and running

REQUEST HTTP HEADERS


Accept:

Only accept application/json type

Authorization:

The value of the header is Bearer access_token

X-DFS-API-PLAN:

Name of the API plan assigned to the app during registration approval

SAMPLE CURL REQUEST

curl --include --header "x-dfs-c-app-cert:sampleconsumercertificate" \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--header "Cache-Control:no-store" \
--header "x-dfs-api-plan:sampleapiplan" \
--header "Content-Type:application/json" \
--request POST \
--data '{

} '\
'/dci/atm/v1/locations'

RESPONSE VALUES


message: string

service/API is up and running or Down

status: string

UP or Down

Sample response

HTTP 200
{
"details": {
"message": "service/API is up and running"
} ,

"status":"UP"


}

Errors


Header Level Error Codes

Error Code Error Message Error Description HTTP Status Code
90001 Invalid field type - Latitude Latitude must only contain numbers 400
90002 Invalid field type - Longitude Longitude must only contain numbers 400
90003 Invalid field type - View View can be either Y or N 400
90004 Invalid field type - Radius Radius must only contain numbers 400
90005 Invalid field type - Maxresults Maxresults must only contain numbers 400