Merchant Place [Deprecated]
How to build a Merchant Place Query
Merchants API is deprecated as of January 01, 2023, and will be turned off on December 31, 2023.
The Woosmap Merchant API supports POST request, passing in your “dirty” transactions as JSON objects in the request body. There are currently two different endpoints which allow retrieving different level of information. Here is how to retrieve a Google Maps Place ID in addition to clean names and logos.
Requests should be built as follows:
https://api.woosmap.com/merchants/place
?private_key=YOUR_PRIVATE_API_KEY
curl -L -X POST 'https://api.woosmap.com/merchants/place?private_key=YOUR_PRIVATE_API_KEY' \
-H 'content-type: application/json' \
--data-raw '{
"merchants": [
{
"dirty_name": "MCDO UK 2231 EP",
"country": "GB",
"merchant_id": "234482729011"
},
{
"dirty_name": "Zara Fashion Retail, S.A.",
"country": "IT",
"merchant_id": "*44532UY2T33219"
},
{
"dirty_name": "CARREFOUR CITY 3112846",
"country": "FR",
"merchant_id": "9651781125"
},
{
"dirty_name": "ITUNES.COM/BILL",
"country": "IE",
"merchant_id": "2070070200925"
},
{
"dirty_name": "Pepa SL Gracia",
"country": "ES",
"merchant_id": "34J21189"
}
]
}'
var axios = require('axios');
var data = JSON.stringify({
"merchants": [
{
"dirty_name": "MCDO UK 2231 EP",
"country": "GB",
"merchant_id": "234482729011"
},
{
"dirty_name": "Zara Fashion Retail, S.A.",
"country": "IT",
"merchant_id": "*44532UY2T33219"
},
{
"dirty_name": "CARREFOUR CITY 3112846",
"country": "FR",
"merchant_id": "9651781125"
},
{
"dirty_name": "ITUNES.COM/BILL",
"country": "IE",
"merchant_id": "2070070200925"
},
{
"dirty_name": "Pepa SL Gracia",
"country": "ES",
"merchant_id": "34J21189"
}
]
});
var config = {
method: 'post',
url: 'https://api.woosmap.com/merchants/place?private_key=YOUR_PRIVATE_API_KEY',
headers: {
'content-type': 'application/json'
},
data : data
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
import requests
import json
url = "https://api.woosmap.com/merchants/place?private_key=YOUR_PRIVATE_API_KEY"
payload = json.dumps({
"merchants": [
{
"dirty_name": "MCDO UK 2231 EP",
"country": "GB",
"merchant_id": "234482729011"
},
{
"dirty_name": "Zara Fashion Retail, S.A.",
"country": "IT",
"merchant_id": "*44532UY2T33219"
},
{
"dirty_name": "CARREFOUR CITY 3112846",
"country": "FR",
"merchant_id": "9651781125"
},
{
"dirty_name": "ITUNES.COM/BILL",
"country": "IE",
"merchant_id": "2070070200925"
},
{
"dirty_name": "Pepa SL Gracia",
"country": "ES",
"merchant_id": "34J21189"
}
]
})
headers = {
'content-type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"merchants\": [\n {\n \"dirty_name\": \"MCDO UK 2231 EP\",\n \"country\": \"GB\",\n \"merchant_id\": \"234482729011\"\n },\n {\n \"dirty_name\": \"Zara Fashion Retail, S.A.\",\n \"country\": \"IT\",\n \"merchant_id\": \"*44532UY2T33219\"\n },\n {\n \"dirty_name\": \"CARREFOUR CITY 3112846\",\n \"country\": \"FR\",\n \"merchant_id\": \"9651781125\"\n },\n {\n \"dirty_name\": \"ITUNES.COM/BILL\",\n \"country\": \"IE\",\n \"merchant_id\": \"2070070200925\"\n },\n {\n \"dirty_name\": \"Pepa SL Gracia\",\n \"country\": \"ES\",\n \"merchant_id\": \"34J21189\"\n }\n ]\n}");
Request request = new Request.Builder()
.url("https://api.woosmap.com/merchants/place?private_key=YOUR_PRIVATE_API_KEY")
.method("POST", body)
.addHeader("content-type", "application/json")
.build();
Response response = client.newCall(request).execute();
require "uri"
require "json"
require "net/http"
url = URI("https://api.woosmap.com/merchants/place?private_key=YOUR_PRIVATE_API_KEY")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Post.new(url)
request["content-type"] = "application/json"
request.body = JSON.dump({
"merchants": [
{
"dirty_name": "MCDO UK 2231 EP",
"country": "GB",
"merchant_id": "234482729011"
},
{
"dirty_name": "Zara Fashion Retail, S.A.",
"country": "IT",
"merchant_id": "*44532UY2T33219"
},
{
"dirty_name": "CARREFOUR CITY 3112846",
"country": "FR",
"merchant_id": "9651781125"
},
{
"dirty_name": "ITUNES.COM/BILL",
"country": "IE",
"merchant_id": "2070070200925"
},
{
"dirty_name": "Pepa SL Gracia",
"country": "ES",
"merchant_id": "34J21189"
}
]
})
response = https.request(request)
puts response.read_body
Required parameters
Some parameters are required to initiate a Merchant API request on the Place endpoint. These parameters are specified below. Only the API key is set in the URL parameters. Other parameters are set in the body of the request.
https://api.woosmap.com/merchants/place?private_key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx
private_key
It is your own project’s API key. This key identifies your Woosmap Project for purposes of quota management. We recommend using a private key to perform queries to the API.
Said API key should be set as Read Only.
Please refer to the documentation to get an API key if necessary.
dirty_name
The dirty_name is the unique merchant identifier which is provided on transactions by a payment provider.
merchant_id
The merchant_id, also known as MID, is a code attached to a merchant name in the transaction’s payload of the payment
provider.
country
The country field is mandatory on the Place endpoint. The API accepts ISO-3166-1-alpha2 country codes only.
One POST request cannot accept more than 1000 dirty merchants. If you need to clean more merchants, please do multiple
requests.
Optional parameters
The parameters below are non-mandatory but are highly recommended to retrieve a Place ID.
description
The description is provided to you by the payment provider and is the transaction description attached to any payment.
street
The merchant’s street, typically found in the raw transaction.
zipcode
The merchant’s zipcode.
city
The merchant’s city.
state
The merchant’s state.
position
The geographic coordinates where the transaction occurred. Retrieving this information can be achieved by leveraging our open-source Geofencing SDK (see our Community website to access it). Sending in a position will significantly increase the possibility of finding a Place ID.
Merchant Place API Response
The Woosmap Merchant API provides a JSON response containing an array of merchants, each
containing dirty_name, country, clean_name, logo, logo_url and status.
{
"merchants":
[
{
"dirty_name": "MCDO UK 2231 EP",
"clean_name": "McDonald's",
"status": "OK",
"logo": "419b279b6609768a3106ce5a5b4dd70b",
"logo_url": "https://api.woosmap.com/merchants/logos/419b279b6609768a3106ce5a5b4dd70b.png",
"country": "GB",
"merchant_id": "234482729011",
"place_id": "ChIJGS7Sga0cdkgR46nd-S661TM",
},
{
"dirty_name": "Zara Fashion Retail, S.A.",
"clean_name": "Zara",
"status": "OK",
"logo": "72fc39033e0d9e923a0236cb874c9309",
"logo_url": "https://api.woosmap.com/merchants/logos/72fc39033e0d9e923a0236cb874c9309.png",
"country": "IT",
"merchant_id": "*44532UY2T33219",
"place_id": "ChIJF2vQecLGhkcR83Zbpwpej3I",
},
{
"dirty_name": "CARREFOUR CITY 3112846",
"clean_name": "Carrefour City",
"status": "OK",
"logo": "08ee8a3cecbcd3b7d9103bcf0e04db7e",
"logo_url": "https://api.woosmap.com/merchants/logos/08ee8a3cecbcd3b7d9103bcf0e04db7e.png",
"country": "FR",
"merchant_id": "9651781125",
"place_id": "ChIJJ7ZEZDUnVQ0Ru5gudUqdvKM",
},
{
"dirty_name": "ITUNES.COM/BILL",
"clean_name": "Apple",
"status": "OK",
"logo": "5eb75a5239b76287f44021f8e6e1bd41",
"logo_url": "https://api.woosmap.com/merchants/logos/5eb75a5239b76287f44021f8e6e1bd41.png",
"country": "IE",
"merchant_id": "2070070200925",
"place_id": "",
},
{
"status": "OK",
"clean_name": "",
"logo": "",
"logo_url": "",
"country": "ES",
"dirty_name": "Pepa SL Gracia",
"merchant_id": "34J21189",
"place_id": "ChIJZ9fQvb2ipBIRyaZy8wUqRGQ",
},
],
}
Merchants
Each merchant contains the following fields:
dirty_name: The merchant’s dirty name.
clean_name: A clean name for the above merchant, when available.
status: See Status Codes for a list of possible status codes.
logo: This is a hash generated for the logo based on the image.
logo_url: The logo image with image/png content-type.
country: The merchant’s country.
merchant_id: Provided by you and return to help you to sort results.
place_id : The Google Maps Place ID of the merchant’s location.
Status Codes
OK when an information is found on a dirty merchant. It can be a clean name, a logo, a Place ID, or all of them.
NOT_FOUND when no added information can be returned for the transaction.
Example
Here is a sample of Merchant API call using JavaScript.