Skip to content

Location API v2 documentation

Jump to bottom
delereyus edited this page Sep 16, 2021 · 36 revisions

Changes from v1

Description

shortDescription and longDescription has been moved to a description node and renamed to short and long.

Pending Changes

When a location is updated changes to address and location (lat/lon) are put in a pending change state and needs to be reviewed in Listings.

The data returned under address and location is the values that are presented on the location details in listings, values yet to be applied are returned under the pendingChanges node. A change can either be applied or ignored in listings depending on the quality of the data sent.

Special Open Hours

startDate and endDate are now named start and end, the format has changed to be YYYY-MM-DD

Images

Links to cover and profile images on facebook & google.

Foursquare

Foursquare and Factual have merged. Foursquare is removed from network since Foursquare no longer has a 2-way API.

General

PinMeTo API v2 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, temporarilyClosedUntil: formatted YYYY-MM-DD, to unset send '' or null
  • SpecialOpenHours: use ISO 8601 formatting of date strings ie. YYYY-MM-DD
    • 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

  • An 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

Custom Data

If the account have custom data enabled you can get, set and update that data

Fetch all locations

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

Endpoint /v2/<<account_id>>/locations

https://api.pinmeto.com/v2/<<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)
    • description: (Object)
      • short: (String, max length 240)
      • long: (String, max length 750)
    • openingDate: (String)
    • contact: (Object)
      • phone: (String)
      • homepage: (String)
      • email: (String)
    • address: (Object)
      • street: (String)
      • zip: (String)
      • city: (String)
      • country: (String)
    • permanentlyClosed: (Boolean)
    • temporarilyClosedUntil: (ISO Date string, YYYY-MM-DD)
    • 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)
      • start: (ISO Date string, YYYY-MM-DD)
      • end: (ISO Date string, YYYY-MM-DD)
      • openTime: (String)
      • endTime: (String)
      • isClosed: (Boolean)
    • network: (Object)
      • facebook: (Object)
        • pageId: (String)
        • link: (String)
        • profileImage: (String)
        • coverImage: (String)
      • google: (Object)
        • placeId: (String)
        • link: (String)
        • newReviewUrl: (String)
        • profileImage: (String)
        • coverImage: (String)
      • bing: (Object)
        • link: (String)
    • googleName: (String) - if google custom name is enabled
    • facebookName: (String) - if facebook custom name is enabled
    • wifiSsid: (String, max length 32)
    • pendingChanges: (Object)
      • address: (Object)
        • street: (String)
        • zip: (String)
        • city: (String)
        • country: (String)
      • location : (Object)
        • lat: (Number)
        • lon: (Number)
    • customData: (Object, depends on your custom data definition)

Example result

{
  "data": [
    {
      "name": "Name of location"
      "storeId": "api-location",
      "description": {
        "short": "The location marketing platform for chain businesses.",
        "long": "The location marketing platform for chain businesses."
      },
      "openingDate": "2013-02-01",
      "contact": {
        "phone": "+46 70 2336879",
        "homepage": "http://www.google.com",
        "email": "test@pinmeto.com"
      },
      "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": [
        {
          "start": "2017-05-28",
          "end": "2017-05-28",
          "openTime": "1000",
          "closeTime": "2000",
          "isClosed": false,
          "label": "Mothers day"
        },
        {
          "start": "2017-07-04",
          "end": "2017-07-04",
          "openTime": "0000",
          "closeTime": "0000",
          "isClosed": true,
          "label": "Independence day"
        },
        {
          "start": "2017-11-24",
          "end": "2017-11-24",
          "openTime": "0000",
          "closeTime": "2400",
          "isClosed": false,
          "label": "Black friday"
        }
      ],
      "network": {
        "facebook": {
          "pageId": "1605390276379843",
          "link": "https://www.facebook.com/Pinmeto.Malmo/"
          "profileImage": "https://scontent-arn2-1.xx.fbcdn.net/v/t1.0-1/p720x720/78063569_2439243212994541_4444163125444345856_o.jpg?_nc_cat=103&_nc_sid=0c64ff&_nc_ohc=empRK1Pb1KoAX900cWE&_nc_ht=scontent-arn2-1.xx&tp=6&oh=76e3097e2e0b63b528bc355b9ea07083&oe=5F9BB09B",
          "coverImage": "https://scontent-arn2-2.xx.fbcdn.net/v/t1.0-9/s720x720/103323620_2607531456165715_1759303419147657987_o.jpg?_nc_cat=100&_nc_sid=dd9801&_nc_ohc=ZfPnPPzbMUEAX-sbjis&_nc_ht=scontent-arn2-2.xx&tp=7&oh=0b2ae55c8118bf0ecdd4839677e1528b&oe=5F9A4ADA"
        },
        "google": {
          "placeId": "ChIJpbpzuV6hU0YRG49xL3Bp8m8",
          "link": "https://maps.google.com/?cid=8066625813127204635",
          "newReviewUrl": "https://search.google.com/local/writereview?placeid=ChIJF9eIJ12dX0YRogcSnTh1G6s",
          "profileImage": "https://lh3.googleusercontent.com/lCki9MaIOKvhpvwBh_AExUE3_liYXv-8vyr2RH4EPrkSt90__vZImAKkzllwq85JV3PZtUxl8dWivdc7=s0",
          "coverImage": "https://lh3.googleusercontent.com/FrmkuiTtzLt8LbiPHHcoJlJtK1Ab21YahnQKRjs-5Nd7cv_yRwigjodcWy59xNE_frU-9dqT90e5WuWd=s0"
        },
    "wifiSsid": "pinmeto",
        "pendingChanges": {
          "address": {
            "street": "Adelgatan 11"
          },
        "location": {
          "lon": 13.00093,
          "lat": 55.60736
         }
        }
      },
        ...
      {
        "name": "Name of location",
        "storeId": "store-id",
        "description": {
          "short": "The location marketing platform for chain businesses.",
          "long": "The location marketing platform for chain businesses."
        },
        "contact": {
          "phone": "+46 70 2336879",
          "homepage": "http://www.google.com",
          "email": "test@pinmeto.com"
        },
        "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": [
          {
            "start": "2017-05-28",
            "end": "2017-05-28",
            "openTime": "1000",
            "closeTime": "2000",
            "isClosed": false,
            "label": "Mothers day"
          },
          {
            "start": "2017-07-04",
            "end": "2017-07-04",
            "openTime": "0000",
            "closeTime": "0000",
            "isClosed": true,
            "label": "Independence day"
          },
          {
            "start": "2017-11-24",
            "end": "2017-11-24",
            "openTime": "0000",
            "closeTime": "2400",
            "isClosed": false,
            "label": "Black friday"
          }
        ],
        "network": {
          "facebook": {
            "pageId": "1605390276379843",
            "link": "https://www.facebook.com/Pinmeto.Malmo/",
            "profileImage": "https://scontent-arn2-1.xx.fbcdn.net/v/t1.0-1/p720x720/78063569_2439243212994541_4444163125444345856_o.jpg?_nc_cat=103&_nc_sid=0c64ff&_nc_ohc=empRK1Pb1KoAX900cWE&_nc_ht=scontent-arn2-1.xx&tp=6&oh=76e3097e2e0b63b528bc355b9ea07083&oe=5F9BB09B",
            "coverImage": "https://scontent-arn2-2.xx.fbcdn.net/v/t1.0-9/s720x720/103323620_2607531456165715_1759303419147657987_o.jpg?_nc_cat=100&_nc_sid=dd9801&_nc_ohc=ZfPnPPzbMUEAX-sbjis&_nc_ht=scontent-arn2-2.xx&tp=7&oh=0b2ae55c8118bf0ecdd4839677e1528b&oe=5F9A4ADA"
          },
          "google": {
            "placeId": "ChIJpbpzuV6hU0YRG49xL3Bp8m8",
            "link": "https://maps.google.com/?cid=8066625813127204635",
            "newReviewUrl": "https://search.google.com/local/writereview?placeid=ChIJF9eIJ12dX0YRogcSnTh1G6s",
            "profileImage": "https://lh3.googleusercontent.com/lCki9MaIOKvhpvwBh_AExUE3_liYXv-8vyr2RH4EPrkSt90__vZImAKkzllwq85JV3PZtUxl8dWivdc7=s0",
            "coverImage": "https://lh3.googleusercontent.com/FrmkuiTtzLt8LbiPHHcoJlJtK1Ab21YahnQKRjs-5Nd7cv_yRwigjodcWy59xNE_frU-9dqT90e5WuWd=s0"
          },
        "googleName": "custom google name",
        "facebookName": "custom fb name",
        "wifiSsid": "pinmeto"
      }
    ],
    "paging": {
        before: "https://api.pinmeto.com/v2/pinmeto/locations?before=569649b49c5ec8685e11175e"
        next: "https://api.pinmeto.com/v2/pinmeto/locations?next=569652a91151474860f5e173"
    }
  }

Curl call to get all locations

curl -X GET https://api.pinmeto.com/v2/<<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: /v2/<<account_id>>/locations/YOUR_STORE_ID

https://api.pinmeto.com/v2/<<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)
    • description: (Object)
      • short: (String, max length 240)
      • long: (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)
    • temporarilyClosedUntil: (ISO Date string, YYYY-MM-DD)
    • 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)
      • start: (ISO Date string, YYYY-MM-DD)
      • end: (ISO Date string, YYYY-MM-DD)
      • openTime: (String)
      • endTime: (String)
      • isClosed: (Boolean)
    • network: (Object)
      • facebook: (Object)
        • pageId: (String)
        • link: (String)
        • profileImage: (String)
        • coverImage: (String)
      • google: (Object)
        • placeId: (String)
        • link: (String)
        • newReviewUrl: (String)
        • profileImage: (String)
        • coverImage: (String)
      • bing: (Object)
        • link: (String)
    • googleName: (String) - if google custom name is enabled
    • facebookName: (String) - if facebook custom name is enabled
    • wifiSsid: (String, max length 32)
    • pendingChanges: (Object)
      • address: (Object)
        • street: (String)
        • zip: (String)
        • city: (String)
        • country: (String)
      • location : (Object)
        • lat: (Number)
        • lon: (Number)
      • customData: (Object, depends on your custom data definition)

Example result

{
  "data": {
    "name": "Name of location"
		"storeId": "1337",
		"description": {
			"short": "The location marketing platform for chain businesses.",
			"long": "The location marketing platform for chain businesses.",
		},
    "contact": {
      "phone": "+46 739 60 61 40",
      "email": "hello@pinmeto.com",
      "homepage": "http://www.pinmeto.com/"
    },
    "permanentlyClosed": false,
    "temporarilyClosedUntil": "2020-10-30",
    "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": [
      {
        "start": "2017-05-28",
        "end": "2017-05-28",
        "openTime": "1000",
        "closeTime": "2000",
        "isClosed": false,
        "label": "Mothers day"
      },
      {
        "start": "2017-07-04",
        "end": "2017-07-04",
        "openTime": "0000",
        "closeTime": "0000",
        "isClosed": true,
        "label": "Independence day"
      },
      {
        "start": "2017-11-24",
        "end": "2017-11-24",
        "openTime": "0000",
        "closeTime": "2400",
        "isClosed": false,
        "label": "Black friday"
      }
    ],
    "network": {
      "facebook": {
        "pageId": "1605390276379843",
        "link": "https://www.facebook.com/Pinmeto.Malmo/",
		"profileImage": "https://scontent-arn2-1.xx.fbcdn.net/v/t1.0-1/p720x720/78063569_2439243212994541_4444163125444345856_o.jpg?_nc_cat=103&_nc_sid=0c64ff&_nc_ohc=empRK1Pb1KoAX900cWE&_nc_ht=scontent-arn2-1.xx&tp=6&oh=76e3097e2e0b63b528bc355b9ea07083&oe=5F9BB09B",
		"coverImage": "https://scontent-arn2-2.xx.fbcdn.net/v/t1.0-9/s720x720/103323620_2607531456165715_1759303419147657987_o.jpg?_nc_cat=100&_nc_sid=dd9801&_nc_ohc=ZfPnPPzbMUEAX-sbjis&_nc_ht=scontent-arn2-2.xx&tp=7&oh=0b2ae55c8118bf0ecdd4839677e1528b&oe=5F9A4ADA"
      },
      "google": {
        "placeId": "ChIJpbpzuV6hU0YRG49xL3Bp8m8",
        "link": "https://maps.google.com/?cid=8066625813127204635",
		"newReviewUrl": "https://search.google.com/local/writereview?placeid=ChIJF9eIJ12dX0YRogcSnTh1G6s",
		"profileImage": "https://lh3.googleusercontent.com/lCki9MaIOKvhpvwBh_AExUE3_liYXv-8vyr2RH4EPrkSt90__vZImAKkzllwq85JV3PZtUxl8dWivdc7=s0",
		"coverImage": "https://lh3.googleusercontent.com/FrmkuiTtzLt8LbiPHHcoJlJtK1Ab21YahnQKRjs-5Nd7cv_yRwigjodcWy59xNE_frU-9dqT90e5WuWd=s0"
      },
    },
    "googleName": "custom google name",
    "facebookName": "custom fb name",
    "wifiSsid": "pinmeto",
    "pendingChanges": {
        "address": {
            "street": "Adelgatan 11"
        },
        "location": {
            "lon": 13.00093,
            "lat": 55.60736
        }
    }
  }
}

Curl call to get a location

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

Update 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 PUT: /v2/<<account_id>>/locations/YOUR_STORE_ID

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

Properties to update

  • description: (Object)
    • short: (String, max length 240)
    • long: (String, max length 750)
  • contact: (Object)
    • phone: (String)
    • homepage: (String)
    • email: (String)
  • address: (Object)
    • street: (String)
    • zip: (String)
    • city: (String)
    • country: (String)
  • permanentlyClosed: (Boolean)
  • temporarilyClosedUntil: (ISO Date string, YYYY-MM-DD)
  • 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)
    • start: (ISO Date string, YYYY-MM-DD)
    • end: (ISO Date string, YYYY-MM-DD)
    • openTime: (String)
    • endTime: (String)
    • isClosed: (Boolean)
  • googleName: (String) - if google custom name is enabled
  • facebookName: (String) - if facebook custom name is enabled
  • wifiSsid: (String, max length 32)
  • customData: (Object, depends on your custom data definition)

Example of PUT request with access_token in Authorization-header

PUT /v2/<<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": "test@example.com",
		"homepage": "http://www.google.com"
	}
}

Example of PUT request with access_token in the body

PUT /v2/<<<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: 'test@example.com',
		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'='[{"start": "2018-12-31","end":"2018-12-31","openTime":"1100", "closeTime": "1500", "isClosed": false, "label":"New Years Eve"}]' https://api.pinmeto.com/v2/<<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: /v2/<<account_id>>/locations

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

Properties

  • name: (String)
  • storeId: (String) required
  • description: (Object)
    • short: (String, max length 240)
    • long: (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)
  • temporarilyClosedUntil: (ISO Date string, YYYY-MM-DD)
  • 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)
    • start: (ISO Date string, YYYY-MM-DD)
    • end: (ISO Date strin, YYYY-MM-DD)
    • openTime: (String)
    • endTime: (String)
    • isClosed: (Boolean)
  • googleName: (String) - if google custom name is enabled
  • facebookName: (String) - if facebook custom name is enabled
  • wifiSsid: (String, max length 32)
  • customData: (Object, depends on your custom data definition)

Example of POST with token in Authorization-header

POST /v2/<<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": "test@example.com",
		"homepage": "http://www.google.com"
	}
}

Example of POST with token in body

POST /v2/<<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: 'test@example.com',
		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": "test@example.com","homepage": "http://www.google.com"}}' https://api.pinmeto.com/v2/&lt;&lt;account_id&gt;&gt;/locations/?access_token=YOUR_ACCESS_TOKEN

"Upsert" a location

If a querystring parameter upsert=true is passed to Create location it will check if a location with the storeId in the request body already exist, if it does it will do an update instead. If the location doesn't exist it will be created.

Endpoint POST: /v2/<<account_id>>/locations?upsert=true

https://api.pinmeto.com/v2/<<account_id>>/locations?upsert=true

Error Codes

Create location:

400: StoreId must be unique

400: (If validation fails there is a number of validation errors that can be returned)

422: Missing required property, expected "${required}" to be present.

500: Location already exists

Update location:

400: No properties to update, wrong content-type?

400: (If validation fails there is a number of validation errors that can be returned)

404: No location found

Get locations:

404: Site not found

Get location:

404: Location with storeId ${storeId} not found

If an error not covered by these messages occurs, a status code of 500 will be returned with the message “An error occurred.”

Clone this wiki locally