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:




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:




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:

.




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
/Optional
Description
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

FieldTypeRequired
/Optional
Description
addressStringRequiredLocation address and Zip Code or State, Province, or Territory to search locations
countryString
Min Length: 2
Max Length: 2
RequiredCountry code (ISO alpha-2 code)
searchRadiusNumberRequiredSearch radius in miles
limitNumberOptionalLimit for Locations will default to ten if not entered
transactionAmountNumberOptionalTransaction amount for filtering locations that can handle this amount



Response Fields

FieldTypeRequired/
Optional
Description
radiusNumberOptionalSearch radius in miles
locations.locationDetails.nameStringOptionalLocation Name
locations.locationDetails.locationIdStringOptionalUnique location identifier
locations.locationDetails.kioskIdStringOptionalKiosk Identifier
location.locationDetails.addressLine1StringOptionalPrimary address line
location.locationDetails.addressLine2StringOptionalSecondary address line
location.locationDetails.addressLine3StringOptionalThird address line
location.locationDetails.cityStringOptionalCity name
location.locationDetails.stateStringOptionalState or Province
location.locationDetails.countryString
Max Length: 3
OptionalCountry code (ISO alpha-3 code)
location.locationDetails.postalCodeStringOptionalPostal or ZIP code
location.locationDetails.ratailerIdStringOptionalRetailer identifier
location.locationDetails.pwcStringOptionalPWC Code
location.locationDetails.bankAccountRequiredStringOptionalBank account requirement flag
location.locationDetails.distanceNumber OptionalDistance from the search location
location.locationDetails.distanceuomStringOptionalDistance unit of measure
location,locationDetails.latitiudeNumberOptionalLocation latitude
location.locationDetails.longitudeNumber OptionalLocation longitude
locationOperatingHours.monHoursStringOptionalMonday operating hours
locationOperatingHours.tueHoursStringOptionalTuesday operating hours
locationOperatingHours.wedHoursStringOptionalWednesday operating hours
locationOperatingHours.thuHoursStringOptionalThursday operating hours
locationOperatingHours.friHoursStringOptionalFriday operating hours
locationOperatingHours.satHoursStringOptionalSaturday operating hours
locationOperatingHours.sunHoursStringOptionalSunday operating hours
locationPhone.addToPhoneStringOptionalAdd to phone flag
locationPhone.phoneStringOptionalPhone Number
locationServices.amazonCardStringOptionalAmazon card service availability
locationServices.sendMoneyStringOptionalSend money service availability
locationServices.receiveMoneyStringOptionalReceive money service availability
locationServices.billPaymentStringOptionalBill payment service availability
locationServices.reloadOtherCardStringOptionalReload other card service availability
locationServices.addToPhoneStringOptionalAdd to phone service availability
locationServices.paypalStringOptionalPayPal service availability
locationServices.moneyOrderStringOptionalMoney order service availability
locationServices.recCurrenciesStringOptionalReceive currencies supported
locationServices.sendCurrenciesStringOptionalSend currencies supported
locationServices.xpressPackageStringOptionalExpress package service availability
locationServices.purchaseMoneygramCardStringOptionalPurchase MoneyGram card service availability
locationServices.reloadMoneygramCardStringOptionalReload MoneyGram card service availability
locationServices.receiveToCardStringOptionalReceive to card service availability
locationServices.expressPaymentStringOptionalExpress payment service availability
locationServices.formfreeCompletionStringOptionalForm free completion service availability
locationServices.directToAccountStringOptionalDirect to account service availability
locationServices.payWithCashStringOptionalPay with cash service availability