GET Retrieve Locations

'GET /agentlocator/v2/locations'

Development Guide:

The Locator API module retrieves locations available to send or receive money with MoneyGram's services within a specified radius of address entered.


1. Prepare headers & authentication:

Call the 'Retrieve Locations' endpoint with a GET HTTP method, providing the OAuth access_token in the header and all other required header values


Note: MoneyGram uses the OAuth 2.0 framework. The application must use their OAuth client credentials to generate an accessToken by calling the Get access token endpoint. The token is valid for **1 hour ** and must be passed as a header value in all subsequent API HTTP calls. Learn More


🚀

Launch Code Example:

👉 Agent Locator - Headers




2. Provide address, country, & searchRadius as query parameters:

The application must enter the address, country, and searchRadius as query parameters, to retrieve an array of agent locations. Here is an overview of the following query parameters:


  • address [Required]: the application can enter partial or complete address data. For accurate result it is recommended to provide full address, including state and postal code. By default, the Locator endpoint will return the ten nearest agent locations to the address [unless specified in the limit parameter].

  • country [Required]: use 2 digital ISO code of the country

  • searchRadius [Required]: the application needs to specify the search radius in miles and there is no limit to the radius that can be entered. By default, the Agent Locator API will return the ten nearest agent locations to the address, within the specified radius. If there are no locations within the desired searchRadius, the Agent Locator will automatically retrieve the next nearest 10 locations outside the radius.

  • Limit [Optional]: the application can use the limit parameter to specify the number of locations returned within the radius. This is useful if the application wants to return more than the default 10 locations. To confirm: if no value is provided in the limit field, the endpoint will always return the 10 nearest agent locations by default.

  • transactionAmount [Optional]: if the transaction amount is specified, only agent locations capable of handling the specified payout amount will be shown. This is particularly useful when querying agent locations that can handle high-value payouts.

🚀

Launch Code Example:

👉 Agent Locator - Query Parameters




3. Make the request and handle the response:

The application must call the 'Retrieve Locations' endpoint with a GET HTTP method. The Agent Locator API will respond with a HTTP 200 OK Status and an array of locations in the search radius requested.


  • Success | Parse the Response | 200 OK HTTP Status
    An array of locations will be returned with associated meta-data including: distance, latitude, longitude, locationOperatingHours, locationPhone, and locationServices. The Locator endpoint will always return the ten nearest agent locations by default [unless specified on the limit parameter]

  • Success | Agent Location search has no content | 204 No Content HTTP Status
    When the 'Agent Location API' responds with 204 HTTP Status, the request has been successful but "No Content" can be found matching the search parameters.

  • Failed | Handle the Error | 400 Bad Request HTTP Status
    When the 'Retrieve Agent Locator' endpoint responds with 400 HTTP Status, specific error code/s will be returned with an array of offending fields. The application will need to resolve these errors and resubmit the request.

🚀

Launch Code Example:

👉 Agent Locator - 200 OK

👉 Agent Locator - 400 Bad Request




4. You're done! Communicate the locationDetails to the customer

The application can use the array of locations on a map feature, using the distance, latitude and longitude returned in the response. The "locationDetails" can be used to provide further information about the location's operating hours, contact details and the MoneyGram services offered at the store.






Code Examples

const axios = require('axios');
const { v4: uuidv4 } = require('uuid');

const fxRate = async () => {

    // Step 1: Read configuration values with upmost security
    const token = "your_access_token_from_oauth_response"
    // For production - api.moneygram.com & For test - sandboxapi.moneygram.com
    const host = "sandboxapi.moneygram.com";
    const url = 'https://' + host + '/agentlocator/v2/locations';

    // Step 2: Create the GET request headers & params
    const headers = {
        'Content-Type': 'application/json',
        'X-MG-ClientRequestId': uuidv4(), // New UUID for each request tracing
        'Authorization': 'Bearer ' + token,
    };
    
    const params = {
        address: "locationaddress",
        country: "USA",
        radius: "10"
     }

    try {
        // Step 3: Send the request and obtain the response
        axios.get(url, { params, headers })
            .then(function (response) {
                // Step 4: Parse the success response and process further
                console.log(JSON.stringify(response.data, null, 2))
            })
            .catch(function (error) {
                // Step 5: Parse the error response and handle the errors
                if (error.response) {
                    console.log('Response status:', error.response.status);
                    console.log('Response body:', error.response.data);
                } else {
                    // TODO: handle generic errors
                    console.error('Error:', error.message);
                }
            });
    } catch (error) {
        // TODO: handle exception
        console.error('Error:', error.message);
    }
};

locations();
import requests
import uuid
import json

def fx_rate():

    # Step 1: Read configuration values with upmost security
    token = "your_access_token_from_oauth_response"
    # For production - api.moneygram.com & For test - sandboxapi.moneygram.com
    host = "sandboxapi.moneygram.com";
    url = 'https://' + host + '/fx-rate/v1/rates';

    # Step 2: Create the GET request headers & params
    headers = {
        'Content-Type': 'application/json',
        'X-MG-ClientRequestId': str(uuid.uuid4()), # New UUID for each request tracing
        'Authorization': 'Bearer ' + token,
    }

    params = {
        'address': 'locationaddress',
        'country': 'USA',
        'radius': '10'
    }

    try:
        # Step 3: Send the request and obtain the response
        response = requests.get(url, params=params, headers=headers)

        # Step 4: Parse the success response and process further
        if response.status_code == 200:
            parsed_response = json.dumps(json.loads(response.text), indent=2)
            print(parsed_response)
        else:
            # Print the error message if request fails
            # TODO: handle exception
            print("Request failed with status code:", response.status_code)
            print(json.loads(json.dumps(response.text, indent=4)))

    except requests.exceptions.RequestException as e:
        # Print any error that occurred during the request
        # TODO: handle exception
        print("An error occurred:", e)

locations()
package agent_locator;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.UUID;

public class FxRate {

    public static void main(String[] args) {
        // Step 1: Read configuration values with upmost security
        String token = "your_access_token_from_oauth_response";

        // For production - api.moneygram.com & For test - sandboxapi.moneygram.com
        String host = "sandboxapi.moneygram.com";

        // Step 2: Create the GET request headers & params
        // Mandatory Query params
        String address = "locationaddress";
        String country = "USA";
        Number radius = "10";
        
        String uri = "https://" + host + "/agentlocator/v2/locations?"
                + "address=" + address
                + "&country=" + country
                + "&radius=" + radius;

        HttpClient httpClient = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(uri))
                .GET()
                .setHeader("Authorization", "Bearer " + token)
                .setHeader("X-MG-ClientRequestId", String.valueOf(UUID.randomUUID()))
                .build();

        try {
            // Step 3: Send the request and obtain the response
            HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

            // Retrieve the status code and body from the response
            int statusCode = response.statusCode();

            // Step 4: Parse the success response and process further
            if (statusCode == 200) {
                String responseBody = response.body();
                System.out.println(responseBody);
            } else {
                // Step 5: Parse the error response and handle the errors
                String responseBody = response.body();
                System.out.println(responseBody);
            }
        } catch (Exception e) {
            e.printStackTrace();
            // TODO: handle exception
        }

    }
}


API Structure


Header Parameters

FieldTypeRequired/OptionalDescription
X-MG-ClientRequestIdStringOptionalClient Request ID that can be passed by the client application. Client request ID must be unique within a single session for unique requests. This attribute can be used for ensuring idempotent request processing for some APIs. MoneyGram recommends using a UUID for the value of this field.
X-MG-ConsumerIPAddressStringOptionalIP Address of the system initiating the session



Query Parameters

Field

Type

Required/Optional

Description

address

String

Required

Location address and Zip Code or State, Province, or Territory to search locations

country

String
Min Length: 2
Max Length: 2

Required

Country code (ISO alpha-2 code)

searchRadius

Number

Required

Search radius in miles

limit

Number

Optional

Limit for Locations will default to ten if not entered

transactionAmount

Number

Optional

Transaction amount for filtering locations that can handle this amount




Response Fields

Field

Type

Required/ Optional

Description

radius

Number

Optional

Search radius in miles

locations.locationDetails.name

String

Optional

Location Name

locations.locationDetails.locationId

String

Optional

Unique location identifier

locations.locationDetails.kioskId

String

Optional

Kiosk Identifier

location.locationDetails.addressLine1

String

Optional

Primary address line

location.locationDetails.addressLine2

String

Optional

Secondary address line

location.locationDetails.addressLine3

String

Optional

Third address line

location.locationDetails.city

String

Optional

City name

location.locationDetails.state

String

Optional

State or Province

location.locationDetails.country

String
Max Length: 3

Optional

Country code (ISO alpha-3 code)

location.locationDetails.postalCode

String

Optional

Postal or ZIP code

location.locationDetails.ratailerId

String

Optional

Retailer identifier

location.locationDetails.pwc

String

Optional

PWC Code

location.locationDetails.bankAccountRequired

String

Optional

Bank account requirement flag

location.locationDetails.distance

Number

Optional

Distance from the search location

location.locationDetails.distanceuom

String

Optional

Distance unit of measure

location,locationDetails.latitiude

Number

Optional

Location latitude

location.locationDetails.longitude

Number

Optional

Location longitude

locationOperatingHours.monHours

String

Optional

Monday operating hours

locationOperatingHours.tueHours

String

Optional

Tuesday operating hours

locationOperatingHours.wedHours

String

Optional

Wednesday operating hours

locationOperatingHours.thuHours

String

Optional

Thursday operating hours

locationOperatingHours.friHours

String

Optional

Friday operating hours

locationOperatingHours.satHours

String

Optional

Saturday operating hours

locationOperatingHours.sunHours

String

Optional

Sunday operating hours

locationPhone.addToPhone

String

Optional

Add to phone flag

locationPhone.phone

String

Optional

Phone Number

locationServices.amazonCard

String

Optional

Amazon card service availability

locationServices.sendMoney

String

Optional

Send money service availability

locationServices.receiveMoney

String

Optional

Receive money service availability

locationServices.billPayment

String

Optional

Bill payment service availability

locationServices.reloadOtherCard

String

Optional

Reload other card service availability

locationServices.addToPhone

String

Optional

Add to phone service availability

locationServices.paypal

String

Optional

PayPal service availability

locationServices.moneyOrder

String

Optional

Money order service availability

locationServices.recCurrencies

String

Optional

Receive currencies supported

locationServices.sendCurrencies

String

Optional

Send currencies supported

locationServices.xpressPackage

String

Optional

Express package service availability

locationServices.purchaseMoneygramCard

String

Optional

Purchase MoneyGram card service availability

locationServices.reloadMoneygramCard

String

Optional

Reload MoneyGram card service availability

locationServices.receiveToCard

String

Optional

Receive to card service availability

locationServices.expressPayment

String

Optional

Express payment service availability

locationServices.formfreeCompletion

String

Optional

Form free completion service availability

locationServices.directToAccount

String

Optional

Direct to account service availability

locationServices.payWithCash

String

Optional

Pay with cash service availability