Skip to content

API Documentation

Jump to bottom
Fredrik Leijon edited this page Jan 14, 2020 · 17 revisions

General

PinMeTo API v1 is JSON API for get and update information about your locations.

Login into Listings to get these keys:

  • AccountId, <<account_id>>
  • App id, <<app_id>>
  • App Secret, <<app_secret>>

Field encoding notes:

  • OpeningDate: formatted YYYY-MM-DD
  • SpecialOpenHours: use ISO 8601 formatting of strings ie. YYYY-MM-DDTHH:mm:ss.sssZ
    • When setting closed dates (isClosed: true) an entry is needed for each day that is closed.
    • Cannot last longer than 24 hours, must end at latest 1159.

Recommendations

  • A accesstoken is valid for 1 hour so do cache it
  • When using this api to build a storelocator do cache the result on your webserver and avoid calling /locations for every search

Rate limit

You are allowed to do 3600 request/hour. In the header from each response you get information about your ratelimit

Example of ratelimit in header
HEADER
	x-ratelimit-limit: '3600'
	x-ratelimit-reset: '1452787466'
	x-ratelimit-remaining: '3599'
	content-type: 'application/json; charset=utf-8'
	content-length: '2564'
	date: 'Thu, 14 Jan 2016 15:04:25 GMT'

Access Token

Documented here

Fetch all locations

If you have your access token you can get information about all your locations.

Endpoint /v1/<<account_id>>/locations

https://api.pinmeto.com/v1/<<account_id>>/locations?access_token=YOUR_ACCESS_TOKEN

Parameters

  • access_token = (String) your access token to validate your request | required
  • pagesize = (Number) Number of locations that the request returns, default 100, max 250 | optional
  • next = (String) Id of starting point to next page
  • before = (String) Id of starting point to previous page
Result
  • paging: (Object)
    • next: (String) | Url to get next page with locations
    • before: (String) | Url to get previous page with locations
  • data: (Array)
    • name: (String)
    • storeId: (String)
    • shortDescription: (String, max length 240)
    • longDescription: (String, max length 750)
    • text (deprecated, use shortDescription) : (String)
    • openingDate: (String)
    • contact: (Object)
      • phone: (String)
      • homepage: (String)
      • email: (String)
    • address: (Object)
      • street: (String)
      • zip: (String)
      • city: (String)
      • country: (String)
    • permanentlyClosed: (Boolean)
    • isAlwaysOpen: (Boolean)
    • locationDescriptor: (String)
    • location: (Object)
      • lat: (Number)
      • lon: (Number)
    • openHours: (Object)
      • mon: (Object)
        • state: (String)
        • span: (Array)
          • open: (String)
          • close: (String)
      • ...
      • sun: (Object)
        • state: (String)
        • span: (Array)
          • open: (String)
          • close: (String)
    • specialOpenHours: (Array)
      • label: (String)
      • startDate: (ISO Date string)
      • endDate: (ISO Date string)
      • openTime: (String)
      • endTime: (String)
      • isClosed: (Boolean)
    • network: (Object)
      • facebook: (Object)
        • pageId: (String)
        • link: (String)
      • google: (Object)
        • placeId: (String)
        • link: (String)
        • newReviewUrl: (String)
      • foursquare: (Object)
        • venueId: (String)
        • link: (String)
      • bing: (Object)
        • link: (String)
    • wifiSsid: (String, max length 32)
Example result
{
  "data": [
    {
      "name": "Name of location"
		"storeId": "api-location",
      "text": "The location marketing platform for chain businesses.",
      "shortDescription": "The location marketing platform for chain businesses.",
      "longDescription": "The location marketing platform for chain businesses.",
      "openingDate": "2013-02-01",
      "contact": {
        "phone": "+46 70 2336879",
        "homepage": "http://www.google.com",
        "email": "[email protected]"
      },
      "address": {
        "street": "testgatan 4",
        "zip": "217 41",
        "city": "Malmö",
        "country": "Sweden"
      },
      "locationDescriptor": "API locationDescriptor",
      "location": {
        "lat": 59.333755678571,
        "lon": 18.056143908447
      },
      "openHours": {
        "mon": {
          "state": "Open",
          "span": [
            {
              "open": "0900",
              "close": "1700"
            }
          ]
        },
        "tue": {
          "state": "Open",
          "span": [
            {
              "open": "0900",
              "close": "1700"
            }
          ]
        },
        "wed": {
          "state": "Open",
          "span": [
            {
              "open": "0900",
              "close": "1700"
            }
          ]
        },
        "thu": {
          "state": "Open",
          "span": [
            {
              "open": "0900",
              "close": "1500"
            }
          ]
        },
        "fri": {
          "state": "Open",
          "span": [
            {
              "open": "0900",
              "close": "1700"
            }
          ]
        },
        "sat": {
          "state": "Closed",
          "span": []
        },
        "sun": {
          "state": "Closed",
          "span": []
        }
      },
      "specialOpenHours": [
        {
          "startDate": "2017-05-28T00:00:00.000Z",
          "endDate": "2017-05-28T00:00:00.000Z",
          "openTime": "1000",
          "closeTime": "2000",
          "isClosed": false,
          "label": "Mothers day"
        },
        {
          "startDate": "2017-07-04T00:00:00.000Z",
          "endDate": "2017-07-04T00:00:00.000Z",
          "openTime": "0000",
          "closeTime": "0000",
          "isClosed": true,
          "label": "Independence day"
        },
        {
          "startDate": "2017-11-24T00:00:00.000Z",
          "endDate": "2017-11-24T00:00:00.000Z",
          "openTime": "0000",
          "closeTime": "2400",
          "isClosed": false,
          "label": "Black friday"
        }
      ],
      "network": {
        "facebook": {
          "pageId": "1605390276379843",
          "link": "https://www.facebook.com/Pinmeto.Malmo/"
        },
        "google": {
          "placeId": "ChIJpbpzuV6hU0YRG49xL3Bp8m8",
          "link": "https://maps.google.com/?cid=8066625813127204635",
          "newReviewUrl": "https://search.google.com/local/writereview?placeid=ChIJF9eIJ12dX0YRogcSnTh1G6s"
        },
        "foursquare": {
          "venueId": "5263ffd511d2505034dc70ac",
          "link": "https://foursquare.com/v/5263ffd511d2505034dc70ac"
        },
        "wifiSsid": "pinmeto"
      },
		...
      {
        "name": "Name of location",
        "storeId": "store-id",
        "shortDescription": "The location marketing platform for chain businesses.",
        "longDescription": "The location marketing platform for chain businesses.",
        "contact": {
          "phone": "+46 70 2336879",
          "homepage": "http://www.google.com",
          "email": "[email protected]"
        },
        "address": {
          "street": "testgatan 2",
          "zip": "217 41",
          "city": "Malmö",
          "country": "Sweden"
        },
        "locationDescriptor": "API locationDescriptor",
        "location": {
          "lat": 9.333755678571002,
          "lon": 8.056143908447002
        },
        "openHours": {
          "mon": {
            "state": "Open",
            "span": [
              {
                "open": "0900",
                "close": "1700"
              }
            ]
          },
          "tue": {
            "state": "Open",
            "span": [
              {
                "open": "0900",
                "close": "1700"
              }
            ]
          },
          "wed": {
            "state": "Open",
            "span": [
              {
                "open": "0900",
                "close": "1700"
              }
            ]
          },
          "thu": {
            "state": "Open",
            "span": [
              {
                "open": "0900",
                "close": "1500"
              }
            ]
          },
          "fri": {
            "state": "Open",
            "span": [
              {
                "open": "0900",
                "close": "1700"
              }
            ]
          },
          "sat": {
            "state": "Closed",
            "span": []
          },
          "sun": {
            "state": "Closed",
            "span": []
          }
        },
        "specialOpenHours": [
          {
            "startDate": "2017-05-28T00:00:00.000Z",
            "endDate": "2017-05-28T00:00:00.000Z",
            "openTime": "1000",
            "closeTime": "2000",
            "isClosed": false,
            "label": "Mothers day"
          },
          {
            "startDate": "2017-07-04T00:00:00.000Z",
            "endDate": "2017-07-04T00:00:00.000Z",
            "openTime": "0000",
            "closeTime": "0000",
            "isClosed": true,
            "label": "Independence day"
          },
          {
            "startDate": "2017-11-24T00:00:00.000Z",
            "endDate": "2017-11-24T00:00:00.000Z",
            "openTime": "0000",
            "closeTime": "2400",
            "isClosed": false,
            "label": "Black friday"
          }
        ],
        "network": {
          "facebook": {
            "pageId": "1605390276379843",
            "link": "https://www.facebook.com/Pinmeto.Malmo/"
          },
          "google": {
            "placeId": "ChIJpbpzuV6hU0YRG49xL3Bp8m8",
            "link": "https://maps.google.com/?cid=8066625813127204635"
          },
          "foursquare": {
            "venueId": "5263ffd511d2505034dc70ac",
            "link": "https://foursquare.com/v/5263ffd511d2505034dc70ac"
          }
        },
        "wifiSsid": "pinmeto"
      }
    ],
    "paging": {
	before: "https://api.pinmeto.com/v1/pinmeto/locations?before=569649b49c5ec8685e11175e"
	next: "https://api.pinmeto.com/v1/pinmeto/locations?next=569652a91151474860f5e173"
    }
  }

Curl call to get all locations

curl -X GET https://api.pinmeto.com/v1/<<account_id>>/locations/?access_token=YOUR_ACCESS_TOKEN

Fetch one location

If you have your access token you can get information about one location

Endpoint GET: /v1/<<account_id>>/locations/YOUR_STORE_ID

https://api.pinmeto.com/v1/<<account_id>>/locations/YOUR_STORE_ID/?access_token=YOUR_ACCESS_TOKEN

Parameters
  • access_token = (String) your access token to validate your request | required
Result
  • data: (Object)
    • name: (String)
    • storeId: (String)
    • shortDescription: (String, max length 240)
    • longDescription: (String, max length 750)
    • text (deprecated, use shortDescription) : (String)
    • contact: (Object)
      • phone: (String)
      • homepage: (String)
      • email: (String)
    • address: (Object)
      • street: (String)
      • zip: (String)
      • city: (String)
      • country: (String)
    • permanentlyClosed: (Boolean)
    • isAlwaysOpen: (Boolean)
    • locationDescriptor: (String)
    • location: (Object)
      • lat: (Number)
      • lon: (Number)
    • openHours: (Object)
      • mon: (Object)
        • state: (String)
        • span: (Array)
          • open: (String)
          • close: (String)
      • ...
      • sun: (Object)
        • state: (String)
        • span: (Array)
          • open: (String)
          • close: (String)
    • specialOpenHours: (Array)
      • label: (String)
      • startDate: (ISO Date string)
      • endDate: (ISO Date string)
      • openTime: (String)
      • endTime: (String)
      • isClosed: (Boolean)
    • network: (Object)
      • facebook: (Object)
        • pageId: (String)
        • link: (String)
      • google: (Object)
        • placeId: (String)
        • link: (String)
      • foursquare: (Object)
        • venueId: (String)
        • link: (String)
      • bing: (Object)
        • link: (String)
    • wifiSsid: (String, max length 32)
Example result
{
  "data": {
    "name": "Name of location"
    "storeId": "1337",
    "shortDescription": "The location marketing platform for chain businesses.",
    "longDescription": "The location marketing platform for chain businesses.",
    "contact": {
      "phone": "+46 739 60 61 40",
      "email": "[email protected]",
      "homepage": "http://www.pinmeto.com/"
    },
    "permanentlyClosed": false,
    "isAlwaysOpen": false,
    "address": {
      "street": "testgatan 2",
      "zip": "211 19",
      "city": "Malmö",
      "country": "Sweden"
    },
    "locationDescriptor": "Malmö",
    "location": {
      "lat": 55.6105169,
      "lon": 12.9936406
    },
    "openHours": {
      "mon": {
        "state": "Open",
        "span": [
          {
            "open": "0900",
            "close": "1700"
          }
        ]
      },
      "tue": {
        "state": "Open",
        "span": [
          {
            "open": "0900",
            "close": "1700"
          }
        ]
      },
      "wed": {
        "state": "Open",
        "span": [
          {
            "open": "0900",
            "close": "1700"
          }
        ]
      },
      "thu": {
        "state": "Open",
        "span": [
          {
            "open": "0900",
            "close": "1500"
          }
        ]
      },
      "fri": {
        "state": "Open",
        "span": [
          {
            "open": "0900",
            "close": "1700"
          }
        ]
      },
      "sat": {
        "state": "Closed",
        "span": []
      },
      "sun": {
        "state": "Closed",
        "span": []
      }
    },
    "specialOpenHours": [
      {
        "startDate": "2017-05-28T00:00:00.000Z",
        "endDate": "2017-05-28T00:00:00.000Z",
        "openTime": "1000",
        "closeTime": "2000",
        "isClosed": false,
        "label": "Mothers day"
      },
      {
        "startDate": "2017-07-04T00:00:00.000Z",
        "endDate": "2017-07-04T00:00:00.000Z",
        "openTime": "0000",
        "closeTime": "0000",
        "isClosed": true,
        "label": "Independence day"
      },
      {
        "startDate": "2017-11-24T00:00:00.000Z",
        "endDate": "2017-11-24T00:00:00.000Z",
        "openTime": "0000",
        "closeTime": "2400",
        "isClosed": false,
        "label": "Black friday"
      }
    ],
    "network": {
      "facebook": {
        "pageId": "1605390276379843",
        "link": "https://www.facebook.com/Pinmeto.Malmo/"
      },
      "google": {
        "placeId": "ChIJpbpzuV6hU0YRG49xL3Bp8m8",
        "link": "https://maps.google.com/?cid=8066625813127204635"
      },
      "foursquare": {
        "venueId": "5263ffd511d2505034dc70ac",
        "link": "https://foursquare.com/v/5263ffd511d2505034dc70ac"
      }
    },
    "wifiSsid": "pinmeto"
  }
}

Curl call to get a location

curl -X GET https://api.pinmeto.com/v1/<<account_id>>/locations/YOUR_STORE_ID/?access_token=YOUR_ACCESS_TOKEN

Update a location

Note that the name of a location is no longer possible to update using the api. You need to include your access_token in the Authorization header ("Bearer " + YOUR_ACCESS_TOKEN'). Or add access_token : YOUR_ACCESS_TOKEN in the body , but be sure that your request headers is Content-Type: application/x-www-form-urlencoded

Endpoint PUT: /v1/<<account_id>>/locations/YOUR_STORE_ID

https://api.pinmeto.com/v1/<<account_id>>/locations/YOUR_STORE_ID

Properties to update
  • shortDescription: (String, max length 240)
  • longDescription: (String, max length 750)
  • text (deprecated, use shortDescription) : (String)
  • contact: (Object)
    • phone: (String)
    • homepage: (String)
    • email: (String)
  • address: (Object)
    • street: (String)
    • zip: (String)
    • city: (String)
    • country: (String)
  • permanentlyClosed: (Boolean)
  • isAlwaysOpen: (Boolean)
  • locationDescriptor: (String)
  • location: (Object)
    • lat: (Number)
    • lon: (Number)
  • openHours: (Object)
    • mon: (Object)
      • state: (String)
      • span: (Array)
        • open: (String)
        • close: (String)
    • ...
    • sun: (Object)
      • state: (String)
      • span: (Array)
        • open: (String)
        • close: (String)
  • specialOpenHours: (Array)
    • label: (String)
    • startDate: (ISO Date string)
    • endDate: (ISO Date string)
    • openTime: (String)
    • endTime: (String)
    • isClosed: (Boolean)
  • wifiSsid: (String, max length 32)
Example of PUT request with access_token in Authorization-header
PUT /v1/<<account_id>>/locations/YOUR_STORE_ID HTTP/1.1
Authorization: 'Bearer 77813e40da005550c53bd8e06fc59e8ae76e2694'
Host: https://api.pinmeto.com
Content-Type: application/json
Body:
{
	"locationDescriptor": "API locationDescriptor",
	"address": {
		"street": "testgatan 4",
		"zip": "217 41",
		"city": "Malmö",
		"country": "Sweden"
	},
	"location": {
		"lat": 59.333755678571,
		"lon": 18.056143908447
	},
	"contact": {
		"phone": "+46 70 2336879",
		"email": "[email protected]",
		"homepage": "http://www.google.com"
	}
}
Example of PUT request with access_token in the body
PUT /v1/<<<account_id>>>/locations/YOUR_STORE_ID HTTP/1.1
Host: https://api.pinmeto.com
Content-Type: 'application/x-www-form-urlencoded'
Body:
{
	access_token: 'e7ecec1fd6b460fc2e2d12d8890a13368b497327',
	locationDescriptor: 'API locationDescriptor',
	address: {
		street: 'testgatan 4',
		zip: '217 41',
		city: 'Malmö',
		country: 'Sweden'
	},
	location: {
		lat: 59.333755678571,
		lon: 18.056143908447
	},
	contact: {
		phone: '+46 70 2336879',
		email: '[email protected]',
		homepage: 'http://www.google.com'
	}
}

Curl call to update a location

curl -X PUT -H "Content-Type: application/x-www-form-urlencoded" -d 'locationDescriptor'='Malmoe' -d 'specialOpenHours'='[{"startDate": "2018-12-31","endDate":"2018-12-31","openTime":"1100", "closeTime": "1500", "isClosed": false, "label":"New Years Eve"}]' https://api.pinmeto.com/v1/<<account_id>>/locations/YOUR_STORE_ID/?access_token=YOUR_ACCESS_TOKEN

Create a location

You need to include your access_token in the Authorization header ("Bearer " + YOUR_ACCESS_TOKEN'). Or add access_token : YOUR_ACCESS_TOKEN in the body , but be sure that your request headers is Content-Type: application/x-www-form-urlencoded

Endpoint POST: /v1/<<account_id>>/locations

https://api.pinmeto.com/v1/<<account_id>>/locations

Properties
  • storeId: (String) required
  • shortDescription: (String, max length 240)
  • longDescription: (String, max length 750)
  • text (deprecated, use shortDescription) : (String)
  • contact: (Object) required
    • phone: (String)
    • homepage: (String)
    • email: (String)
  • address: (Object) required
    • street: (String)
    • zip: (String)
    • city: (String)
    • country: (String)
  • permanentlyClosed: (Boolean)
  • isAlwaysOpen: (Boolean)
  • locationDescriptor: (String)
  • location: (Object) required
    • lat: (Number)
    • lon: (Number)
  • openHours: (Object)
    • mon: (Object)
      • state: (String)
      • span: (Array)
        • open: (String)
        • close: (String)
    • ...
    • sun: (Object)
      • state: (String)
      • span: (Array)
        • open: (String)
        • close: (String)
  • specialOpenHours: (Array)
    • label: (String)
    • startDate: (ISO Date string)
    • endDate: (ISO Date string)
    • openTime: (String)
    • endTime: (String)
    • isClosed: (Boolean)
  • wifiSsid: (String, max length 32)
Example of POST with token in Authorization-header
POST /v1/<<account_id>>/locations HTTP/1.1
Authorization: 'Bearer 77813e40da005550c53bd8e06fc59e8ae76e2694'
Host: https://api.pinmeto.com
Content-Type: application/json
Body:
{
	"storeId": "store-id",
	"locationDescriptor": "API locationDescriptor",
	"address": {
		"street": "testgatan 4",
		"zip": "217 41",
		"city": "Malmö",
		"country": "Sweden"
	},
	"location": {
		"lat": 59.333755678571,
		"lon": 18.056143908447
	},
	"contact": {
		"phone": "+46 70 2336879",
		"email": "[email protected]",
		"homepage": "http://www.google.com"
	}
}
Example of POST with token in body
POST /v1/<<account_id>>/locations HTTP/1.1
Host: https://api.pinmeto.com
Content-Type: 'application/x-www-form-urlencoded'
Body:
{
	access_token: 'token'
	storeId: 'store-id',
	locationDescriptor: 'API locationDescriptor',
	address: {
		street: 'testgatan 4',
		zip: '217 41',
		city: 'Malmö',
		country: 'Sweden'
	},
	location: {
		lat: 59.333755678571,
		lon: 18.056143908447
	},
	contact: {
		phone: '+46 70 2336879',
		email: '[email protected]',
		homepage: 'http://www.google.com'
	}
}

Curl call to create a location:

curl -H "Content-Type: application/json" --data '{ "storeId": "0987654", "locationDescriptor": "API locationDescriptor","address": {"street": "testgatan 4","zip": "217 41","city": "Malmö","country": "Sweden"},"location": {"lat": 59.333755678571,"lon": 18.056143908447},"contact": {"phone": "+46 70 2336879","email": "[email protected]","homepage": "http://www.google.com"}}' https://api.pinmeto.com/v1/&lt;&lt;account_id&gt;&gt;/locations/?access_token=YOUR_ACCESS_TOKEN

Clone this wiki locally