Create a new market opportunity analysis
https://api.faraday.ai/v1/market_opportunity_analysesAuthentication
Provide your API key in the Authorization header. You can find your API key in the Settings page of the dashboard.
Authorization: Bearer YOUR_TOKENBody
aggregatestringThe entity this analysis counts. person (the default) counts individuals. residence counts households: people at the same address collapse into one entity before any metric is computed.
How a hou...
"person"person, residencelocationsobjectThe atlas locations this analysis covers. If absent, the analysis is not based on locations.
not allowedHuman-readable label for this market opportunity analysis
^(?!\s*$).+64Outcome must be in the scope payload.
persona_idstring<uuid>persona_id must belong to the persona_set_id chosen. Providing a persona_id will do further analysis on the persona, but is not required to generate results for the persona set as a whole.
persona_set_idstring<uuid>Optionally select a persona set to analyze. Persona set must be in the scope payload.
Responses
201Created market opportunity analysis
aggregatestringThe entity this analysis counts. person (the default) counts individuals. residence counts households: people at the same address collapse into one entity before any metric is computed.
How a hou...
"person"person, residencearchived_atstring<date-time>If not null, this resource will no longer receive updates, but will still be visable.
When this resource was created. It says nothing about builds; to check status, see Status and timestamps.
google_sheets_urlstring<uri>URL to the Google Sheets spreadsheet of the market opportunity analysis. Available once the market opportunity analysis has been run. Permission to view the spreadsheet is granted to all users on the current account.
google_slides_urlstring<uri>URL to the Google Slides presentation of the market opportunity analysis. Available once the market opportunity analysis has been run. Permission to view the presentation is granted to all users on the current account.
A unique ID for this resource.
last_read_input_atstring<date-time>When the latest finished build started reading this resource's configuration and inputs; omitted until the first build finishes. Once this is at or after last_updated_config_at, a build with the cur...
last_updated_config_atstring<date-time>When Faraday registered the latest change to this resource's configuration, or the latest force_update. A create, update or force_update response carries the value then on record (an update that c...
last_updated_output_atstring<date-time>When a build last changed this resource's output. A build that finishes with nothing new to write does not move it.
locationsobjectThe atlas locations this analysis covers. If absent, the analysis is not based on locations.
not allowedHuman-readable label for this market opportunity analysis
^(?!\s*$).+64Outcome must be in the scope payload.
overall_reportobjectSummary over the latest report. Available once the market opportunity analysis has been run.
persona_idstring<uuid>persona_id must belong to the persona_set_id chosen. Providing a persona_id will do further analysis on the persona, but is not required to generate results for the persona set as a whole.
persona_set_idstring<uuid>Optionally select a persona set to analyze. Persona set must be in the scope payload.
The type of this resource.
The state of this resource's latest build. Until last_read_input_at is at or after last_updated_config_at, no build with the current configuration has finished (starting or running means one i...
"ready"new, starting, running, ready, errorstatus_changed_atstring<date-time>When the status of this resource was last updated.
status_errorstringIf this resource has status == "error", this will contain an error message.
status_needs_fix_fromstringWhat Faraday is waiting for before it builds a resource with status == "error" again. user: a configuration change to this resource or a force_update. support: Faraday support, and `force_upda...
user, supportWhen this resource was last changed, by an edit or by Faraday while building it. Don't use it to check status; use last_updated_config_at and last_read_input_at as Status and timestamps explains.
400The request was invalid.
A Faraday error code.
Some possible values include:
Generic HTTP Errors
- BAD_REQUEST: The request could not be validated.
- FORBIDDEN: You do not have permission to access the specified resour...
"ERROR_TYPE"BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, INVALID_API_KEY, ACCOUNT_SUSPENDED, ACCOUNT_DELETED, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDEDA unique ID for this error. Please include this in bug reports.
"082f9513-901c-4308-8081-902a8fe22d7e"validationErrorsarray[object]JSON Schema validation errors, if any.
401No API key was supplied.
A Faraday error code.
Some possible values include:
Generic HTTP Errors
- BAD_REQUEST: The request could not be validated.
- FORBIDDEN: You do not have permission to access the specified resour...
"ERROR_TYPE"BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, INVALID_API_KEY, ACCOUNT_SUSPENDED, ACCOUNT_DELETED, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDEDA unique ID for this error. Please include this in bug reports.
"082f9513-901c-4308-8081-902a8fe22d7e"validationErrorsarray[object]JSON Schema validation errors, if any.
403Access to this resource was forbidden.
A Faraday error code.
Some possible values include:
Generic HTTP Errors
- BAD_REQUEST: The request could not be validated.
- FORBIDDEN: You do not have permission to access the specified resour...
"ERROR_TYPE"BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, INVALID_API_KEY, ACCOUNT_SUSPENDED, ACCOUNT_DELETED, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDEDA unique ID for this error. Please include this in bug reports.
"082f9513-901c-4308-8081-902a8fe22d7e"validationErrorsarray[object]JSON Schema validation errors, if any.
404The requested resource ID was not found.
A Faraday error code.
Some possible values include:
Generic HTTP Errors
- BAD_REQUEST: The request could not be validated.
- FORBIDDEN: You do not have permission to access the specified resour...
"ERROR_TYPE"BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, INVALID_API_KEY, ACCOUNT_SUSPENDED, ACCOUNT_DELETED, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDEDA unique ID for this error. Please include this in bug reports.
"082f9513-901c-4308-8081-902a8fe22d7e"validationErrorsarray[object]JSON Schema validation errors, if any.
500An internal server error occurred.
A Faraday error code.
Some possible values include:
Generic HTTP Errors
- BAD_REQUEST: The request could not be validated.
- FORBIDDEN: You do not have permission to access the specified resour...
"ERROR_TYPE"BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, INVALID_API_KEY, ACCOUNT_SUSPENDED, ACCOUNT_DELETED, VALIDATION_FAILED, CONFLICT, QUOTA_EXCEEDEDA unique ID for this error. Please include this in bug reports.
"082f9513-901c-4308-8081-902a8fe22d7e"validationErrorsarray[object]JSON Schema validation errors, if any.
Tags
Test request
Request snippet
curl -X POST 'https://api.faraday.ai/v1/market_opportunity_analyses' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
"aggregate": "person",
"locations": {
"atlas_ids": [
"4c6c0f1e-0a58-4f1a-9c8a-52a1a1a3f5b7"
],
"location_reference_keys": [
"store-042"
],
"property_conditions": [
{
"_eq": "string",
"_gt": 0,
"_gte": 0,
"_in": [
"string"
],
"_lt": 0,
"_lte": 0,
"_matches": "string",
"_neq": "string",
"_nin": [
"string"
],
"_nnull": true,
"_null": true,
"optional": true,
"property": "string"
}
]
},
"name": "string (pattern: ^(?!\\s*$).+)",
"outcome_id": "123e4567-e89b-12d3-a456-426614174000",
"persona_id": "123e4567-e89b-12d3-a456-426614174000",
"persona_set_id": "123e4567-e89b-12d3-a456-426614174000",
"scope_id": "123e4567-e89b-12d3-a456-426614174000"
}'Example response
{
"aggregate": "person",
"archived_at": "2024-01-01T12:00:00Z",
"created_at": "2024-01-01T12:00:00Z",
"google_sheets_url": "https://example.com",
"google_slides_url": "https://example.com",
"id": "123e4567-e89b-12d3-a456-426614174000",
"last_read_input_at": "2024-01-01T12:00:00Z",
"last_updated_config_at": "2024-01-01T12:00:00Z",
"last_updated_output_at": "2024-01-01T12:00:00Z",
"locations": {
"atlas_ids": [
"4c6c0f1e-0a58-4f1a-9c8a-52a1a1a3f5b7"
],
"location_reference_keys": [
"store-042"
],
"property_conditions": [
{
"_eq": "string",
"_gt": 0,
"_gte": 0,
"_in": [
"string"
],
"_lt": 0,
"_lte": 0,
"_matches": "string",
"_neq": "string",
"_nin": [
"string"
],
"_nnull": true,
"_null": true,
"optional": true,
"property": "string"
}
]
},
"name": "string (pattern: ^(?!\\s*$).+)",
"outcome_id": "123e4567-e89b-12d3-a456-426614174000",
"overall_report": {
"adjusted_in_population_attainers": 0,
"average_total_value_per_in_population_attainer": 0,
"average_value_per_in_population_attainment": 0,
"in_population_remaining_attainment_value": 0,
"in_population_remaining_likely_attainers": 0,
"total_value_of_adjusted_in_population_attainment": 0
},
"persona_id": "123e4567-e89b-12d3-a456-426614174000",
"persona_set_id": "123e4567-e89b-12d3-a456-426614174000",
"resource_type": "string",
"scope_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "ready",
"status_changed_at": "2024-01-01T12:00:00Z",
"status_error": "string",
"status_needs_fix_from": "user",
"updated_at": "2024-01-01T12:00:00Z"
}