↑
POIs

Managing your establishments

The POIs API allows you to feed and manage your own database of establishments, making searches customizable according to your needs. All the data created will be linked to the client_ID of the user who made the inclusion/edit and can only be consulted by that user.

How to register and edit a new establishment

Adding and updating establishments is done via the following endpoint (POST method):

The following parameters are required for inclusion or update:

  • id – String with the establishment’s unique identifier. If the ID is already registered, the point of interest will be updated with the information sent;
  • name – String to enter the name of the establishment;
  • category – Category in which the establishment falls;
  • subCategory – Subcategory in which the establishment falls;
  • active – Boolean value to indicate whether the record is active or not (inactive records will not be
    returned in the searches);
  • address – Object with address details:
    • street – String to enter the address;
    • number – String for the establishment number;
    • district – (Optional) String for the neighborhood;
    • city – String for city;
    • state – String for status;
    • zipcode – String for zip code;
    • point – Array with the coordinates of the establishment:
      • latitude – Latitude coordinate in decimal degrees;
      • longitude – Longitude coordinate in decimal degrees;
  • tags – (Optional) Array of strings with “tags”, or labels, to identify the type of establishment with customized categories;
  • phones – (Optional) Array of strings for contact phone numbers.

Note: To consult the categories and subcategories available for consultation and registration, simply make a request to the following endpoints (GET method) https://api.maplink.global/place/v1/places/category and https://api.maplink.global/place/v1/places/subcategory

If you need to update an existing record, simply resend the request indicating the unique ID with all the required parameters and the updated data.

The body of the request should follow the structure below:

{
    "id": "4321",
    "name": "Restaurante Dummy",
    "category": "ALIMENTOS_E_BEBIDAS",
    "subCategory": "RESTAURANTES",
    "address": {
        "street": "Praça Tiradentes",
        "number": "23",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "zipcode": "20060-070",
        "point": {
            "latitude": -22.90741716416432,
            "longitude": -43.182738139927416
        }
    },
    "phones": [
        "(21) 91234-5678"
    ],
    "tags": [
        "Restaurante Self-Service",
        "Restaurante por quilo"
    ],
    "active": true
}

How to consult a registered establishment

To consult all the establishments registered, simply make a GET request to the following endpoint, where the term {{placeId} } must be replaced by the ID of the establishment you want:

How to consult the establishment database

To consult all the registered establishments, simply make a GET request to the following endpoint:

You can filter the query results via parameters in the URL. The following filters are available:

  • city – Filter results by city;
  • district – Filter results by neighborhood or district;
  • state – Filter results by state;
  • tag – Filter results by tag;
  • center – Reference coordinates for the search for results. Format: center=-23.552088765,-46.6341653162;
  • radius – Specifies the search radius, in meters, from the center point set at center.

Example of use:
https://api.maplink.global/place/v1/places?city=Caieiras&state=SP&tags=abc123,restaurante&center=-23.364792,-46.783109&radius=149000&district=Centro

You can also page through the results with the following parameters:

  • offset – Index of the first value;
  • limit – Number of results per page, with a limit of 100.

In the example below, we have 20 establishments registered and we want to paginate the results, with each page containing 10 establishments. To consult the first page we would have:
https://api.maplink.global/place/v1/places?offset=0&limit=10

For the second page we would have https://api.maplink.global/place/v1/places?offset=9&limit=10 and so on.

How to consult the available categories and subcategories

How to consult the available categories and subcategories

To see a list of all the categories available for registration, simply make a GET request to the following endpoint:

To consult the subcategories, use the following endpoint, also with the GET method:

How to check the states, cities and neighborhoods of registered establishments

You can consult the states, cities or neighborhoods where there are establishments registered on the database.

Consult states

To consult the states where there are registered establishments, simply make a GET request to the following endpoint:

The return will come in json format, with an array containing the acronyms of the states where there are registered establishments, as shown in the example below:

[
    "RJ",
    "SP"
]

Consult cities

To consult the cities where there are registered establishments, simply make a GET request to the endpoint below, where the term {{state}} must be replaced by the desired state:

The return will come in json format, with an array containing the cities in the requested state where there are registered establishments, as shown in the example below:

[
    "São Paulo",
    "Ribeirão Preto",
    "Campinas" 
]

Consult neighborhoods

Finally, to consult the neighborhoods where there are registered establishments, simply make a GET request to the endpoint below, where the term {{state}} must be replaced by the desired state and the term {{city}} by the city:

The return will come in json format, with an array containing the neighborhoods of the requested city and state where there are registered establishments, as shown in the example below:

[
    "Sé Bela Vista",
    "Bom Retiro",
    "Cambuci",
    "Aricanduva", 
]