PinMeToAPI PHP Library

PinMeToAPI is a PHP library that provides convenient access to the PinMeTo API, allowing users to interact with PinMeTo's locations data and metrics.

Overview

Integration with PinMeTo offers the ability to fetch information and send updates through PinMeTo API for:

• Locations
• Insights (Google™ and Facebook™)
• Keywords (Google™)
• Reviews (Google™ and Facebook™)

Table Of Content

• Requirements
• Installation
• Usage
  • Get all available locations
  • Get a specific location
  • Create a new location
  • Update an existing location
  • Get locations metrics data
  • Get locations Google keywords
  • Get locations ratings
  • Get network categories
• License
• PinMeTo official API documentation
• Disclaimer
• Laravel package

Requirements

• a PinMeTo user account with API access enabled
• PHP >= 8.0
• PinMeToAPI uses curl extension for handling HTTP calls. So you need to have the curl extension installed and enabled with PHP.
• json support enabled with PHP

Installation

You can install the PinMeToAPI PHP library via Composer. Run the following command in your terminal:

composer require liviu-hariton/pinmeto-php-api

or add the following to your composer.json file

{
  "require": {
    "liviu-hariton/pinmeto-php-api": "^0.1.0"
  }
}

and run Composer's install or update commands to complete installation

composer install

Usage

Make sure to include the autoloader:

require_once 'vendor/autoload.php';

Initialize the PinMeToAPI object with your PinMeTo Account ID, App ID, and App Secret values. You can obtain these credentials from your PinMeTo Account Settings here.

$pinmeto = new LHDev\PinMeToAPI\PinMeToAPI([
    'app_id' => 'PINMETO_APP_ID',
    'app_secret' => 'PINMETO_APP_SECRET',
    'account_id' => 'PINMETO_ACCOUNT_ID',
    'mode' => 'test' // or 'live' for production
]);

Once initialized, you can use various methods provided by the PinMeToAPI class to interact with the PinMeTo API.

Get all available locations

$locations = $pinmeto->getLocations();

Optionally, you can also pass an array of parameters

$parameters = [
    'pagesize' => '2' // Number of locations that the request returns, default 100, max 250
    'next' => '569652a91151474860f5e173', // (string) Id of starting point to next page
    'before' => '569649b49c5ec8685e11175e', // (string) Id of starting point to previous page
];

$locations = $pinmeto->getLocations($parameters);

Get a specific location

$store_id = 8;

$location = $pinmeto->getLocation($store_id);

Create a new location

$parameters = [
    'name' => 'Your store name',
    'storeId' => 'your_store_id',
    'address' => [
        'street' => 'Store address',
        'zip' => 'Zipcode',
        'city' => 'The City',
        'country' => 'The Country',
    ],
    'location' => [
        'lat' => 59.333755678571,
        'lon' => 18.056143908447,
    ],
];

$pinmeto->createLocation($parameters);

You can also use the "Upsert" option by passing an additional parameter

$pinmeto->createLocation($parameters, true);

Update an existing location

$store_id = 8;

$parameters = [
    'name' => 'The new store name',
    'address' => [
        'street' => 'The new store address',
        'zip' => 'Some other zipcode',
        'city' => 'In some other city',
        'country' => 'In some other country',
    ],
];

$pinmeto->updateLocation($store_id, $parameters);

Metrics

Get the Google™ or Facebook™ metrics data for all locations

$metrics = $pinmeto->getMetrics(
    source: 'google', // the source can be either `facebook` or `google`
    from_date: '2024-01-01', // the format is `YYYY-MM-DD`
    to_date: '2024-03-31', // the format is `YYYY-MM-DD`
    fields: [
        'businessImpressionsDesktopMaps', 'businessImpressionsDesktopSearch'
    ] // All available fields are described here https://api.pinmeto.com/documentation/v3/
);

or for a specific location by passing the Store ID

$metrics = $pinmeto->getMetrics(
    source: 'facebook', // the source can be either `facebook` or `google`
    from_date: '2024-01-01', // the format is `YYYY-MM-DD`
    to_date: '2024-03-31', // the format is `YYYY-MM-DD`
    store_id: 8
);

Google keywords

Get the Google™ keywords data for all locations

$keywords = $pinmeto->getKeywords(
    from_date: '2024-01', // the format is `YYYY-MM`
    to_date: '2024-03' // the format is `YYYY-MM`
);

or for a specific location by passing the Store ID

$keywords = $pinmeto->getKeywords(
    from_date: '2024-01', // the format is `YYYY-MM`
    to_date: '2024-03', // the format is `YYYY-MM`
    store_id: 8
);

Ratings

Get the Google™ or Facebook™ ratings data for all locations

$ratings = $pinmeto->getRatings(
    source: 'google', // the source can be either `facebook` or `google`
    from_date: '2024-01-01', // the format is `YYYY-MM-DD`
    to_date: '2024-03-31' // the format is `YYYY-MM-DD`
);

or for a specific location by passing the Store ID

$ratings = $pinmeto->getRatings(
    source: 'facebook', // the source can be either `facebook` or `google`
    from_date: '2024-01-01', // the format is `YYYY-MM-DD`
    to_date: '2024-03-31', // the format is `YYYY-MM-DD`
    store_id: 8
);

Network categories

Get the list of categories per network. The available networks are google or apple or facebook or bing

$category_networks = $pinmeto->getNetworkCategories(
    network: 'apple'
);

Response

For every method described here, the response will be a JSON data format. Please find al the details in the PinMeTo official API documentation.

License

This library is licensed under the MIT License. See the LICENSE.md file for details.

PinMeTo official API documentation

• The V2 documentation (locations data) is available on PinMeTo GitHub
• The V3 documentation (locations metrics) is available on PinMeTo API - Documentation

Disclaimer

I am not affiliated with PinMeTo, but I am a developer who sees the value of their location services and wanted to create tools to simplify integration for the PHP community.

While this library facilitate integration with PinMeTo's location services API, it is a separate entity maintained and supported by me. Any issues, questions, or inquiries related to these library should be directed to me and not to PinMeTo.

I greatly appreciate the availability of PinMeTo's API, which has enabled me to create this library and enhance the functionality of applications that rely on location-based services. However, the development and maintenance of this library is solely my responsibility (and any contributors to this repository).

Feel free to explore this library here on GitHub, contribute, and make the most of PinMeTo’s powerful location services!

Laravel package

A Laravel package is available also here.