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=53211Where {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 |
| Retrieve data |
|
| Create a new record |
|
| Update an existing record |
|
| Remove a record |
|
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.comto your allowed domains in your API Key configuration.
Creating an API Key
Log in to your MetaLocator account.
Navigate to My User Profile → API Keys.
Click New
Choose API Key
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
Which type of API key should I use?
Choose the key with the least access required by your integration:
Use case | Recommended key |
Browser-based locator or JavaScript application | Public |
Native iOS or Android application displaying published data | Public |
Server-side search of published data | Public |
Importing, updating, or deleting account data | Private |
Accessing unpublished or administrative data | Private |
Synchronizing data with a CRM, ERP, or database | Private |
A server-side integration requiring both public and administrative operations | Public and private scopes |
Any application where the key will be distributed to end users | Public only |
Never use a private or mixed-scope key in browser code, a mobile application, a desktop application, or any other software distributed to end users.
What is a public API key?
A public API key provides limited access to public-facing MetaLocator functionality. It can retrieve published data and perform supported actions that are already available through a public MetaLocator Interface, such as searching locations, submitting a lead, or leaving a review.
Public keys are intended for situations where the key may be visible to an end user, including browser-based JavaScript and native mobile applications.
Although a public key has limited permissions, it should still be protected where practical. Configure only the required access, apply allowed domains to browser integrations, monitor its usage, and rotate it if misuse is suspected.
What is a private API key?
A private API key can access administrative resources, including unpublished data and operations that create, update, or delete account data.
Private keys must be treated like passwords. They should only be stored and used in a secure server-side environment. Never place a private key in:
Browser-based JavaScript
HTML source code
An iOS or Android application
A desktop application distributed to users
A public source-code repository
Public documentation or support messages
When should I create a key with both public and private scopes?
Use a mixed-scope key only when a secure server-side integration needs both types of functionality.
For example, a backend synchronization service might need to run Interface-based searches and also update administrative records. Because the key includes private scope, it must be protected exactly like a private key.
Do not use a mixed-scope key merely for convenience. If part of an application runs on an end user’s device, use a separate public key for that component and keep the private key on your server.
Mixed-scope requests should be sent to:
https://admin-api.metalocator.com/api/v1
Which key should I use in browser-based JavaScript?
Use a public-only key and send requests to:
https://api.metalocator.com/api/v1
Add every authorized website origin to the key’s allowed-domain configuration. An origin generally includes the protocol and hostname, such as:
https://www.example.com
Do not place a private or mixed-scope key in JavaScript. Browser code can be inspected by visitors, so any embedded key must be assumed to be visible.
Which key should I use in an iOS or Android application?
Use a public-only key when the application needs access to published search results or other public-facing functionality.
A key embedded in a mobile application cannot be kept permanently secret. Even if it is obfuscated or stored in the device’s secure storage, a determined user may be able to extract it. Therefore, never include a private or mixed-scope key in a mobile application.
What if my mobile application needs unpublished or administrative data?
Route those requests through a secure backend proxy that you control:
The mobile application authenticates the user with your backend.
Your backend confirms that the user is authorized for the requested operation.
Your backend calls the MetaLocator private API using a private key stored on the server.
Your backend returns only the permitted data to the application.
The private key must never be sent to the mobile application.
Which key should I use for a custom locator?
If the locator displays the same published information that could be displayed through a public MetaLocator Interface, use a public key.
The Interface ID included in the request determines which filters, ordering rules, permissions, and other Interface settings are applied to the search.
Which key should I use for a CRM, ERP, or database integration?
Use a private key when the integration runs on a secure server and needs to synchronize, create, update, or delete MetaLocator data.
Examples include:
Importing locations from an ERP
Exporting leads to a CRM
Updating categories or location records
Synchronizing account data on a schedule
Retrieving unpublished records
Store the key in a secrets manager, protected environment variable, or similarly secure server-side configuration. Do not save it directly in source code.
Can I use a private key for a public search application?
A private key may technically include access sufficient for some public operations, but it should not be used in a public application. Doing so exposes significantly more access than the application requires.
Use a separate public-only key for the search application. This limits the impact if the key is copied or misused.
Do allowed domains make a public key private?
No. Allowed domains reduce unauthorized use from browser-based applications, but they do not turn a public key into a secret.
Browser CORS enforcement helps ensure that approved websites can read API responses. It does not prevent someone from seeing the public key, and it does not control requests made outside a browser.
Never rely on allowed domains to protect a private or mixed-scope key.
What should I enter as an allowed domain?
Enter the complete origin from which the browser will call the API, including the protocol and hostname.
Examples:
https://www.example.comhttps://locator.example.comhttps://staging.example.com
Production and staging websites should use separate API keys whenever possible.
To test public API calls using SwaggerHub, add this origin to the key’s allowed domains:
https://metalocator.portal.swaggerhub.com
Why does my browser request fail even though the key has public scope?
Confirm all of the following:
The request is being sent to
https://api.metalocator.com/api/v1.The key includes public scope.
The website’s exact origin is included in the key’s allowed domains.
The requested endpoint supports public access.
The request includes the API key in the required header.
The browser’s origin matches the configured protocol, hostname, and port.
A key that also includes private scope should be treated as private and is not intended for direct browser use.
Why am I receiving an “Invalid credentials” response?
Common causes include:
A public key is being used with a private endpoint.
The request is being sent to the wrong API hostname.
The key was copied incorrectly.
The key has been revoked or replaced.
The requested operation is outside the key’s permitted scope.
Public API requests should use:
https://api.metalocator.com/api/v1
Private and mixed-scope requests should use:
https://admin-api.metalocator.com/api/v1
Why can’t I call a private endpoint from a web page or SwaggerHub?
Private endpoints do not provide CORS access for browser-based requests. This is intentional because private API keys must not be exposed in browser code.
Call private endpoints from a secure server, command-line tool, or API client where the key is not distributed to end users.
Should staging and production use the same key?
No. Create separate keys for staging and production whenever possible.
Separate keys make it easier to:
Limit each environment to the required permissions
Configure different allowed domains
Monitor usage independently
Revoke a staging key without affecting production
Rotate credentials safely
Can MetaLocator retrieve a lost API key?
No. API keys are displayed when created and are not available for later retrieval.
If a key is lost, create a replacement, update the integration, verify that the new key works, and revoke the old key.
What should I do if an API key with private scope may have been exposed?
Replace the key as soon as possible:
Create a new key with only the required scope.
Update the integration to use the new key.
Test the integration.
Revoke the exposed key.
Review recent API usage for unexpected activity.
If a private or mixed-scope key was exposed, treat the incident as a possible compromise of administrative API access.
Will existing Legacy API integrations continue to work?
Yes. There are currently no plans to eliminate the Legacy API. New integrations should use the REST API.
Next Steps
API Reference Guide – Learn about available endpoints and parameters.
Sample Applications – Check out our Github repo for sample applications.