Introduction to the MetaLocator REST API

The MetaLocator REST API provides developers with a flexible and secure way to interact programmatically with their MetaLocator account data and features. It is designed to power integrations, automate workflows, and extend MetaLocator’s functionality beyond the standard web interface.

Whether you’re building a custom search interface, synchronizing data from another system, or embedding MetaLocator features into your own platform, the REST API gives you direct access to key data and operations.

What You Can Do with the REST API

The MetaLocator REST API supports a wide range of use cases, including but not limited to:

Synchronizing Locations and Data: Automatically push or pull location, category, or lead data between MetaLocator and external databases or CRMs.
Building Custom Locator Interfaces: Search locations, categories and custom fields to display results within your own applications.
Automating Tasks: Create, read, update, and delete records programmatically instead of using the web interface.
Integration with Third-Party Systems: Connect MetaLocator to systems such as marketing automation platforms, ERP tools, or mobile apps.

All API endpoints return data in JSON format, making it easy to integrate with virtually any modern programming environment.

Authentication Model

MetaLocator uses a key-based authentication model designed to balance convenience and security. Every API request must include a valid API key as part of the request headers. MetaLocator supports two types of API keys: public and private.

Public API Keys

Public API keys are intended for client-side integrations, such as embedding data into a website or JavaScript application. They are limited in scope and can only perform public-facing actions, such as retrieving locations, categories, or search results. Public keys can only access published data, and access the same "public" functions already exposed via MetaLocator Interfaces, such as creating a new lead or leaving a review.

Public keys are ideal for:

Embedding MetaLocator search results in your own app.
Fetching location data for display.
Reproducing functionality available in public Interfaces, such as creating new Leads, leaving a review.
Client-side integrations where sensitive operations are not required.

Public API Endpoint

API calls for the Public API should be directed at https://api.metalocator.com/api/v1

Public API Calls and MetaLocator Interface Ids

Most public API calls include a MetaLocator Interface ID as a required parameter. For example, the search API path is structured as follows:

https://api.metalocator.com/api/v1/interfaces/{id}/search?postal_code=53211

Where {id} is a MetaLocator-provided Interface ID. The results of the search API call above will include any filters, ordering rules, permissions and settings configured with the Interface provided.

Private API Keys

Private API keys are designed for server-to-server communication or secure backend integrations. They allow full read/write access to your account, including the ability to create, update, or delete data.

Private API keys should never be exposed in client-side code or shared publicly.

They are ideal for:

Automated data synchronization tasks.
Secure integrations with CRMs or external databases.
Managing leads, categories, and records programmatically.

Private API Endpoint

API calls for the Private API should be directed at https://admin-api.metalocator.com/api/v1

Mixed scope API calls (E.g. public and private) should also be directed at https://admin-api.metalocator.com/api/v1

Making Requests

The API follows standard REST conventions. Each endpoint corresponds to a specific resource (e.g., /data, /categories, /leads) and supports common HTTP verbs:

HTTP Method	Action	Example
`GET`	Retrieve data	`GET /`data
`POST`	Create a new record	`POST /`data
`PUT`	Update an existing record	`PUT /data/{id}`
`DELETE`	Remove a record	`DELETE /data/{id}`

All endpoints return standard REST HTTP response codes to indicate success or failure.

Security Best Practices

Always store private keys securely on the server.
Never disclose private keys in client-side code
Use HTTPS for all API requests to protect your credentials.
Rotate keys periodically or when team members change.
Restrict key access based on role or environment when possible (e.g., separate staging and production keys).
Restrict public keys to specific domains by providing allowed origins.

Rate Limiting

API methods employ rate limiting measures to protect our infrastructure and enforce quota limits. The API will return a 429 HTTP response code when rate limits are exceeded.

Rate limits vary based on subscription plan, API endpoint and method. Be sure to author your integration in a manner that expects and supports rate limiting.

CORS

MetaLocator’s public API endpoints support CORS by allowing approved browser-based applications to make direct requests to the API across origins. In practical terms, that means a JavaScript app running on a different domain can call supported public endpoints without needing its own server-side proxy, as long as it uses a public-scoped API key. Some important things to know about MetaLocator's CORS support include:

Designed for browser access: Public endpoints are intended to be callable from client-side applications, not just server-side systems.
Cross-origin requests are allowed: The API includes CORS headers so browsers can complete requests from other origins.
Public-key compatible: These endpoints are built to work with public API keys, so developers can safely use them in front-end applications for approved use cases.
Private keys and endpoints do not support CORS: When using private-scoped API keys, CORS headers will not be included, even if the key also includes public scope.
To test public API calls within Swaggerhub, add https://metalocator.portal.swaggerhub.com to your allowed domains in your API Key configuration.

Getting Started

Log in to your MetaLocator account.
Navigate to My User Profile → API Keys.
Generate a Public and/or Private API key as needed.
Review the API Reference Guide for endpoint details and request examples.
Leverage the Sample Applications for complete examples

Frequently Asked Questions

I have a correct API key, but I'm receiving an "Invalid credentials" response. Keys marked as public cannot be used to call private API endpoints.
Does the API support CORS? Yes. The MetaLocator REST API supports Cross-Origin Resource Sharing (CORS), allowing web applications running in a browser to communicate directly with the API. CORS headers are only sent for public endpoints accessed by a public scoped key.
I see a network error when testing the API in Swaggerhub.
Private methods do not have CORS support and cannot be invoked from a Web page. To test public API calls within Swaggerhub, add https://metalocator.portal.swaggerhub.com to your allowed domains in your API Key configuration.
I lost my API key, can you retrieve it? No, API keys are displayed once and then stored internally as an encrypted hash.
Will our existing API Legacy integrations keep working? Yes. There are no plans to eliminate the old API, but any new integrations should use the new API.
I have a new project, should it have public or private scope? Generally speaking, locator search applications that provide similar functionality to a public-facing Interface should be public scope. Integrations manage modify data should be private scope.

Next Steps

API Reference Guide – Learn about available endpoints and parameters.
Sample Applications – Check out our Github repo for sample applications.

Importing retailers into MetaLocator for product monitoring

Importing Location Data from Yext

Retailer API

Using Google Maps with MetaLocator

Webhook Security