There are copious examples below to help you get started. We cannot currently guarantee that changes through the API will always propagate, but we will do our best. When your app is ready to be published, we’d love to hear from you. A quick look at your app and the data it submits may enable us to increase the expediency with which your data is made visible.
Please note – the API is intended for the use of our developer partners. If you are a SEO Agency/business listings management company and want to submit data to Factual, please contact us to apply to our Trusted Data Contributor program.
The examples below are shown using Factual’s Ruby driver. Factual has drivers for most commonly used languages available here. Also, note that the examples below are writing data to our test environment (us-sandbox). For production submissions, you will use the appropriate place table (by country). For example, the US is places-us. A list of country specific endpoints is available here.
The examples below are not comprehensive. For a full list of writeable fields, refer to the schema for the appropriate dataset.
Important: When you make contributions using the submit API, please be sure to store the commit_id in the JSON response returned from your submission request. Without the commit ID, we will not be able to trace the whereabouts of \
your data for any potential support request.
Here is an example response:
Add or Update a new business
Always submit ALL of the business details you have, even if you are attempting to update a single field.
Do NOT include any existing Factual ID of the business you are attempting to update. If you are working with an existing business, simply add the entire record, as shown above. Factual will attempt to properly match the record to any pre-existing records. If this results in a duplicate, You can separately submit a flag request if the older record needs to be removed, as shown in the examples below.
The hours of operation in the example above show a single set of hours for Monday, two separate hours of operation (with a break in between) for Tuesday through Friday, hours that extend beyond midnight for Saturday, and closed for business Sunday. Time should be in 12 hour format, with ‘am’ or ‘pm’ indicators. Days should be three letter abbreviations (Mon, Tue, Wed, Thu, Fri, Sat, Sun).
International telephone numbers can be in any locally common format.
Clear incorrect data without submitting a correction
Data written through the API should appear within minutes, provided that you are searching for the data using a comprehensive existence threshold. There may be some factors that prevent this from being the case. For example:
A submission does not meet the minimum validation for inclusion: it must either contain a valid postal address or lat/lng
Businesses with spammy names (incorporating deals or SEO-specific tags into the name, etc.) are often flagged and suppressed
You are submitting (on behalf of a third party) a business that we have strong evidence is no longer an ongoing concern. E.g., you are telling us about a business that many other developers or other sources have told us is closed.
What do I do if I submit data through the API and it doesn’t show up in Factual’s data?
Factual provides support at http://support.factual.com. In general, we aim to respond to all support requests within 1 day. For any submit API questions, please make sure to include the commit_id from the API response to your submission(s).