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 - HeadersOpen Recipe
2. Provide address
, country
, & searchRadius
as query parameters:
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 thelimit
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 desiredsearchRadius
, 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 thelimit
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 ParametersOpen Recipe
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 oflocations
will be returned with associated meta-data including:distance
,latitude
,longitude
,locationOperatingHours
,locationPhone
, andlocationServices
. The Locator endpoint will always return the ten nearest agent locations by default [unless specified on thelimit
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 OKOpen Recipe.
👉Agent Locator - 400 Bad RequestOpen Recipe
4. You're done! Communicate the locationDetails
to the customer
locationDetails
to the customerThe 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
Field | Type | Required /Optional | Description |
---|---|---|---|
X-MG-ClientRequestId | String | Optional | Client 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-ConsumerIPAddress | String | Optional | IP 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 |
Updated 1 day ago