{"__v":0,"_id":"5845a4a99f6fbb1b004307f0","category":{"version":"5845a4a89f6fbb1b004307b7","project":"54d3007669578e0d002730c9","_id":"5845a4a89f6fbb1b004307b9","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-07-30T06:25:25.645Z","from_sync":false,"order":1,"slug":"key-concepts","title":"Key Concepts"},"parentDoc":null,"project":"54d3007669578e0d002730c9","user":"55bafe141b0d663700781682","version":{"__v":1,"_id":"5845a4a89f6fbb1b004307b7","project":"54d3007669578e0d002730c9","createdAt":"2016-12-05T17:32:24.708Z","releaseDate":"2016-12-05T17:32:24.708Z","categories":["5845a4a89f6fbb1b004307b8","5845a4a89f6fbb1b004307b9","5845a4a89f6fbb1b004307ba","5845a4a89f6fbb1b004307bb","5845a4a89f6fbb1b004307bc","5845a4a89f6fbb1b004307bd","5845a4a89f6fbb1b004307be","5845a4a89f6fbb1b004307bf","5845a4a89f6fbb1b004307c0"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"25.0.0","version":"25"},"updates":["572043d6a0acd42000af9699","573c9bb305b9a1200042cb1c"],"next":{"pages":[],"description":""},"createdAt":"2015-08-05T06:34:24.370Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"* [Overview](#overview)\n* [Using Entities](#using-entities)\n* [Entity Types](#entity-types)\n * [System Entities](#section-system-entities)\n     + [Generic](#section-generic)\n     + [Date and Time](#section-date-and-time)\n     + [Numbers](#section-numbers)\n     + [Amounts with Units](#section-amounts-with-units)\n     + [Unit Names](#section-unit-names)\n     + [Geography](#section-geography)\n     + [Contacts](#section-contacts)\n     + [Names](#section-names)\n     + [Color](#section-color)     \n     + [Language](#section-language)\n     + [Music](#section-music)     \n * [Developer Entities](#section-developer-entities)\n     + [Developer Mapping Entities](#section-developer-mapping-entities)\n     + [Developer Enum Type Entities](#section-developer-enum-type-entities)\n     + [Developer Composite Entities](#section-developer-composite-entities)\n * [User Entities](#section-user-entities)\n* [Download and Upload Entities](#download-and-upload-entities)\n * [Download Entities](#section-download-entities)\n * [Upload Entities](#section-upload-entities)\n      + [JSON Format](#section-json-format)\n      + [CSV Format](#section-csv-format)\n* [Allow Automated Expansion](#allow-automated-expansion)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Overview\"\n}\n[/block]\nEntities represent concepts and serve as a powerful tool for extracting parameter values from natural language inputs.\n\nThe entities that are used in a particular agent will depend on the parameter values that are expected to be returned as a result of agent functioning. In other words, a developer need not create entities for every concept mentioned in the agent – only for those required for actionable data.\n\nThere are 3 types of entities: **system** (defined by API.AI), **developer** (defined by a developer), and **user** (built for each individual end-user in every request) entities. Furthermore, each of these can be **mapping** (having reference values), **enum type** (having no reference values), or **composite** (containing other entities with aliases and returning object type values).\n\nRead a detailed description of each entity type [below](#entity-types).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using Entities\"\n}\n[/block]\n**In <a href=\"https://docs.api.ai/docs/concept-intents\" target=\"_blank\">intents</a>**, you can reference an entity in two ways:\n\n- As you write <a href=\"https://docs.api.ai/docs/concept-intents#section-example-and-template-modes\" target=\"_blank\">examples</a> in the ‘User Says’ section, the words and phrases that match entities will be highlighted and <a href=\"https://docs.api.ai/docs/concept-intents#section-example-annotation\" target=\"_blank\">annotated</a> automatically. In this case, parameter names will be the same as the corresponding entity names.\n\n- To reference an entity in a <a href=\"https://docs.api.ai/docs/concept-intents#section-example-and-template-modes\" target=\"_blank\">template</a> in the ‘User says’ section, prefix it with an `:::at:::`, such as `@entity`. It can also have an alias, which corresponds to the parameter name: `@entity:alias`.\n\n**In entities**, reference other entities as `@entity` or `@entity:alias`. Aliases are required if you want to <a href=\"https://docs.api.ai/docs/concept-actions#section-extracting-values-from-composite-entities\" target=\"_blank\">extract reference values from composite entities</a>.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Entity Types\"\n}\n[/block]\n##System Entities\n\nThese are pre-built entities provided by API.AI in order to facilitate handling the most popular common concepts.\n\nHere are some examples of system entities, distinguished by their structure:\n\n* System Mapping Entity\n\n`@sys.date` matches common date references such as *\"January 1, 2015\"* or *“The first of January of 2015”* and returns a reference value in ISO-8601 format: `\"2015-01-01T12:00:00-03:00\"`\n\n* System Enum Type Entity\n\n`@sys.color` matches most popular colors and returns the matched color as it is without mapping it to any reference value. For example, shades of red, such as *“scarlet”* or *“crimson”*, won’t be mapped to “red” and will return their original values “scarlet” and “crimson”.\n\n* System Composite Entity\n\n`@sys.unit-currency` is meant for matching amounts of money with indication of currency name, e.g., *“50 euros”* or *“twenty dollars and five cents”*. It returns an object type value consisting of two attribute-value pairs: `{\"amount\":50,\"currency\":\"EUR\"}`\n\nSee the complete list below.\n\n### Generic\n[block:html]\n{\n  \"html\": \"<table>\\n<col width=\\\"15%\\\">\\n<col width=\\\"20%\\\">\\n<col width=\\\"15%\\\">\\n<col width=\\\"25%\\\">\\n  <tr>\\n    <th>Entity Name</th>\\n    <th>Description</th>\\n    <th>Examples</th>\\n    <th>Returned Object Structure</th>\\n  </tr>\\n  <tr>\\n    <td>@sys.any</td>\\n    <td>Matches any non-empty input (1 or more words)<br><br>See the <i class=\\\"fa fa-exclamation-triangle\\\"></i> <strong>Warning</strong> below.</td>\\n    <td>Find a hotel in @sys.any:location</td>\\n    <td>String of the user input: <code>\\\"New York City\\\"</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.url</td>\\n    <td>Matches a url</td>\\n    <td>www.api.ai<br>https://api.ai/</td>\\n    <td>Returns a valid url</td>\\n  </tr>\\n</table>\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"Do not use **@sys.any** in developer entities.\",\n  \"title\": \"Warning\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Special system syntax (can be used in the template mode)\",\n  \"body\": \"`**` – matches any non-empty string (one or more words). Does not return a value.\\n\\n`*` – matches any string or nothing. Does not return a value.\"\n}\n[/block]\n### Date and Time\n[block:html]\n{\n  \"html\": \"<table>\\n<col width=\\\"15%\\\">\\n<col width=\\\"20%\\\">\\n<col width=\\\"15%\\\">\\n<col width=\\\"25%\\\">\\n  <tr>\\n    <th>Entity Name</th>\\n    <th>Description</th>\\n    <th>Examples</th>\\n    <th>Returned Object Structure</th>\\n  </tr>\\n  <tr>\\n    <td>@sys.date</td>\\n    <td>Matches a date.<br>Both absolute and relative dates are supported.</td>\\n    <td>January 1<br>Tomorrow<br>January first</td>\\n    <td>Date in ISO-8601 format: <code>2014-12-31</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.date-time</td>\\n    <td>Matches a date and time.</td>\\n    <td>Tomorrow at 4 pm<br>January 1 at 3 pm</td>\\n    <td>Date/time in ISO-8601 format,<br>including time zone:<br><code>2014-08-09T22:45:29+00:00</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.date-period</td>\\n    <td>Matches a date interval.</td>\\n    <td>April<br>weekend<br>from 1 till 3 of May<br>in 2 days</td>\\n    <td>Date period in ISO-8601 format: <code>2014-01-01/2014-12-31</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.time</td>\\n    <td>Matches a time.</td>\\n    <td>1 pm<br>20:30<br>half past four<br>in 2 minutes</td>\\n    <td>Time in ISO-8601 format (hh:mm:ss): <code>13:30:00</code><br><b>Note:</b> Does not include time zone data.</td>\\n  </tr>\\n  <tr>\\n    <td>@sys.time-period</td>\\n    <td>Matches a time interval.</td>\\n    <td>afternoon<br>tonight<br>from 1 till 3:30 pm</td>\\n    <td>Time period in ISO-8601 format (hh:mm:ss): <code>13:30:00/14:30:00</code><br><b>Note:</b> Does not include time zone data.</td>\\n  </tr>\\n</table>\"\n}\n[/block]\n### Numbers\n[block:html]\n{\n  \"html\": \"<table>\\n<col width=\\\"17%\\\">\\n<col width=\\\"18%\\\">\\n<col width=\\\"15%\\\">\\n<col width=\\\"25%\\\">\\n  <tr>\\n    <th>Entity Name</th>\\n    <th>Description</th>\\n    <th>Examples</th>\\n    <th>Returned Object Structure</th>\\n  </tr>\\n  <tr>\\n    <td>@sys.number</td>\\n    <td>Matches ordinal and cardinal numbers</td>\\n    <td>1<br>1st<br>two hundred thirty</td>\\n    <td>Number, such as <code>10</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.cardinal</td>\\n    <td>Matches cardinal numbers</td>\\n    <td>ten<br>two<br>2<br>10</td>\\n    <td>Returns number, such as <code>10</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.ordinal</td>\\n    <td>Matches ordinal numbers</td>\\n    <td>tenth<br>second<br>2nd<br>10-th<br>10th</td>\\n    <td>Returns integer, such as <code>10</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.number-integer</td>\\n    <td>Matches integers only</td>\\n    <td>12</td>\\n    <td>Returns integer, such as <code>12</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.number-sequence</td>\\n    <td>Matches number sequences</td>\\n    <td>1 2 3 4 5<br>25 35 45 55</td>\\n    <td>Returns integer, such as <code>123</code></td>\\n  </tr>\\n</table>\"\n}\n[/block]\n### Amounts with Units\n[block:html]\n{\n  \"html\": \"<table>\\n<col width=\\\"15%\\\">\\n<col width=\\\"20%\\\">\\n<col width=\\\"15%\\\">\\n<col width=\\\"25%\\\">\\n  <tr>\\n    <th>Entity Name</th>\\n    <th>Description</th>\\n    <th>Examples</th>\\n    <th>Returned Object Structure</th>\\n  </tr>\\n  <tr>\\n\\t<td>@sys.unit-area</td>\\n\\t<td>Matches a number plus units of area</td>\\n\\t<td>ten sq ft<br>5 acres</td>\\n\\t<td>Amount as integer, unit abbreviation as string: <code>{\\\"amount\\\":10,\\\"unit\\\":\\\"sq ft\\\"}</code></td>\\n  </tr>\\n  <tr>\\n\\t<td>@sys.unit-currency</td>\\n\\t<td>Matches a number plus currency name</td>\\n\\t<td>5 dollars<br>25 pounds</td>\\n\\t<td>Integer for amount, string for currency code as per <a href=\\\"https://en.wikipedia.org/wiki/ISO_4217\\\" target=\\\"_blank\\\">ISO 4217</a>: <code>{\\\"amount\\\":5,\\\"currency\\\":\\\"USD\\\"}</code></td>\\n  </tr>\\n  <tr>\\n\\t<td>@sys.unit-length</td>\\n\\t<td>Matches a number plus units of length</td>\\n\\t<td>ten meters<br>5 miles</td>\\n\\t<td>Amount as integer, unit abbreviation as string: <code>{\\\"amount\\\":10,\\\"unit\\\":\\\"m\\\"}</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.unit-speed</td>\\n    <td>Matches a number plus units of speed</td>\\n    <td>5 km/h<br>10 miles per hour</td>\\n    <td>Amount as integer, unit abbreviation as string: <code>{\\\"amount\\\":5,\\\"unit\\\":\\\"km h\\\"}</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.unit-volume</td>\\n    <td>Matches a number plus units of volume</td>\\n    <td>2 liters<br>100 cc</td>\\n    <td>Amount as integer, unit abbreviation as string: <code>{\\\"amount\\\":2,\\\"unit\\\":\\\"L\\\"}</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.unit-weight</td>\\n    <td>Matches a number plus units of weight</td>\\n    <td>5 kilos<br>15 ounces</td>\\n    <td>Amount as integer, unit abbreviation as string: <code>{\\\"amount\\\":5,\\\"unit\\\":\\\"kg\\\"}</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.percentage</td>\\n    <td>Number + percents</td>\\n    <td>1%<br>50%<br>25 percent</td>\\n    <td>Percentage as string, e.g. <code>\\\"25%\\\"</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.temperature</td>\\n    <td>Number + temperature units</td>\\n    <td>12C<br>10°F<br>15 degrees<br>10 degrees celsius</td>\\n    <td>Amount as integer, unit abbreviation as string: <code>{\\\"amount\\\":25,\\\"unit\\\":\\\"F\\\"}</code><br><b>Note:</b> if unit is not specified (e.g. \\\"25 degrees\\\"), \\\"unknown\\\" will be returned:<br><code>{\\\"amount\\\":25,\\\"unit\\\":\\\"unknown\\\"}</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.duration</td>\\n    <td>Number + duration units (seconds, hours, days, months etc.)</td>\\n    <td>5 sec<br>10 minutes<br>5 days<br>3 years</td>\\n    <td>Amount as integer, unit as string: <code>{\\\"amount\\\":10,\\\"unit\\\":\\\"min\\\"}</code><br><code>{\\\"amount\\\":5,\\\"unit\\\":\\\"day\\\"}</code></td>\\n  </tr>\\n  </tr>\\n  <tr>\\n    <td>@sys.age</td>\\n    <td>Number + age units (years old, months old etc.)</td>\\n    <td>5 y.o.<br>10 months old<br>2 weeks old<br>1 day old</td>\\n    <td>Amount as integer, unit as string: <code>{\\\"amount\\\":5,\\\"unit\\\":\\\"year\\\"}</code><br><code>{\\\"amount\\\":10,\\\"unit\\\":\\\"month\\\"}</code></td>\\n  </tr>  \\n</table>\"\n}\n[/block]\n### Unit Names\n[block:html]\n{\n  \"html\": \"<table>\\n<col width=\\\"15%\\\">\\n<col width=\\\"20%\\\">\\n<col width=\\\"15%\\\">\\n<col width=\\\"25%\\\">\\n  <tr>\\n    <th>Entity Name</th>\\n    <th>Description</th>\\n    <th>Examples</th>\\n    <th>Returned Object Structure</th>\\n  </tr>\\n  <tr>\\n\\t\\t<td>@sys.currency-name</td>\\n\\t\\t<td>Currencies</td>\\n\\t\\t<td>USD <br> Dollars <br> Euros</td>\\n\\t\\t<td>String: <code>\\\"USD\\\"</code></td>\\n  </tr>\\n  <tr>\\n\\t\\t<td>@sys.unit-area-name</td>\\n\\t\\t<td>Units of area</td>\\n\\t\\t<td>square meters <br> acres</td>\\n\\t\\t<td>String: <code>\\\"sq m\\\"</code></td>\\n  </tr>\\n  <tr>\\n\\t\\t<td>@sys.unit-length-name</td>\\n\\t\\t<td>Units of length</td>\\n\\t\\t<td>meters <br> centimeter</td>\\n\\t\\t<td>String: <code>\\\"cm\\\"</code></td>\\n  </tr>\\n  <tr>\\n\\t\\t<td>@sys.unit-speed-name</td>\\n\\t\\t<td>Units of speed</td>\\n\\t\\t<td>kilometer per hour <br> miles per second</td>\\n\\t\\t<td>String: <code>\\\"mph\\\"</code></td>\\n  </tr>\\n  <tr>\\n\\t\\t<td>@sys.unit-volume-name</td>\\n\\t\\t<td>Units of volume</td>\\n\\t\\t<td>cubic meters <br> gallons</td>\\n\\t\\t<td>String: <code>\\\"m3\\\"</code></td>\\n  </tr>\\n  <tr>\\n\\t\\t<td>@sys.unit-weight-name</td>\\n\\t\\t<td>Units of weight</td>\\n\\t\\t<td>kilograms <br> ounce</td>\\n\\t\\t<td>String: <code>\\\"kg\\\"</code></td>\\n  </tr>\\n</table>\"\n}\n[/block]\n### Geography\n[block:html]\n{\n  \"html\": \"<table>\\n<col width=\\\"15%\\\">\\n<col width=\\\"20%\\\">\\n<col width=\\\"15%\\\">\\n<col width=\\\"25%\\\">\\n  <tr>\\n    <th>Entity Name</th>\\n    <th>Description</th>\\n    <th>Examples</th>\\n    <th>Returned Object Structure</th>\\n  </tr>\\n  <tr>\\n    <td>@sys.address</td>\\n    <td>Full US address</td>\\n    <td>111 W Evelyn Ave, Sunnyvale, CA 94086</td>\\n    <td>String of the user input: <code>\\\"111 W Evelyn Ave, Sunnyvale, CA 94086\\\"</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.street-address</td>\\n    <td>Part of US address containing either street name or street name in combination with building number and/or suite/office number. Doesn't include city, state, country or zip code.</td>\\n    <td>Evelyn Avenue<br>111 West Evelyn Ave<br>111 W Evelyn Avenue Suite 308</td>\\n    <td>String of the user input: <code>\\\"111 W Evelyn Avenue Suite 308\\\"</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.zip-code</td>\\n    <td>5 digit US postal codes,<br>alphanumeric UK postal codes</td>\\n    <td>94122<br>SW1P 3PA</td>\\n    <td>String: <code>\\\"94122\\\"</code>, <code>\\\"SW1P 3PA\\\"</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.geo-capital</td>\\n    <td>World capitals</td>\\n    <td>Paris<br>Rome</td>\\n    <td>Name of the capital as per <a href=\\\"http://www.unece.org/cefact/locode/service/location.html\\\">UNLOCODE</a> e.g. <code>\\\"Paris\\\"</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.geo-country</td>\\n    <td>Short and full names of country</td>\\n    <td>Great Britain<br>United States</td>\\n    <td>Short country name as per <br><a href=\\\"https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes\\\">ISO 3166-1</a> e.g. <code>\\\"United States of America\\\"</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.geo-country-code</td>\\n    <td>Short and full country names, alpha-2, alpha-3 and numeric codes as per <br><a href=\\\"https://en.wikipedia.org/wiki/ISO_3166-1\\\">ISO 3166-1</a></td>\\n    <td>United Sates<br>US<br>USA<br>840</td>\\n    <td>Strings for name, alpha-2 and alpha-3 codes, integer for numeric code as per <a href=\\\"https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes\\\">ISO 3166-1</a>:<br><code>{\\\"alpha-2\\\":\\\"US\\\",<br>\\\"alpha-3\\\":\\\"USA\\\",<br>\\\"name\\\":\\\"United States of America\\\",<br>\\\"numeric\\\":840}</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.geo-city</td>\\n    <td>Major cities</td>\\n    <td>New York<br>Paris</td>\\n    <td>Name of the city as per <a href=\\\"http://www.unece.org/cefact/locode/service/location.html\\\">UNLOCODE</a>, e.g. <code>\\\"Paris\\\"</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.geo-city-us</td>\\n    <td>US cities</td>\\n    <td>New York<br>San Francisco</td>\\n    <td>Name of the US city as per <a href=\\\"http://www.geonames.org/\\\">geonames</a> excluding unique city names like Friendship</td>\\n  </tr>\\n  <tr>\\n    <td>@sys.geo-state-us</td>\\n    <td>US States</td>\\n    <td>California<br>Virginia</td>\\n    <td>Short name of states according to <a href=\\\"https://en.wikipedia.org/wiki/ISO_3166-2:US\\\">ISO-3166-2</a>, e.g. <code>\\\"California\\\"</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.place-attraction-us</td>\\n    <td>Top US tourist attractions</td>\\n    <td>Central Park<br>Golden Gate Bridge</td>\\n    <td>Name of the attraction as string: <code>\\\"Central Park\\\"</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.airport</td>\\n    <td>Airport names, IATA and ICAO codes</td>\\n    <td>Heathrow Airport<br>SFO<br>KSFO</td>\\n    <td>Strings for country and city of the airport, it's name and IATA/ICAO codes:<br><code>{\\\"country\\\":\\\"United Kingdom\\\",<br>\\\"city\\\":\\\"London\\\",<br>\\\"name\\\":\\\"London Heathrow\\\",<br>\\\"IATA\\\":\\\"LHR\\\",<br>\\\"ICAO\\\":\\\"EGLL\\\"}</code></td>\\n  </tr>\\n</table>\"\n}\n[/block]\n### Contacts\n[block:html]\n{\n  \"html\": \"<table>\\n<col width=\\\"15%\\\">\\n<col width=\\\"20%\\\">\\n<col width=\\\"10%\\\">\\n<col width=\\\"30%\\\">\\n  <tr>\\n    <th>Entity Name</th>\\n    <th>Description</th>\\n    <th>Examples</th>\\n    <th>Returned Object Structure</th>\\n  </tr>\\n  <tr>\\n    <td>@sys.email</td>\\n    <td>email</td>\\n    <td>user@example.com</td>\\n    <td>Email address as string</td>\\n  </tr>\\n  <tr>\\n    <td>@sys.phone-number</td>\\n    <td>Phone number</td>\\n    <td>(123) 456 7890<br>+1 (123) 456-7890</td>\\n    <td>Phone number without punctuation and spaces, e.g. <code>11234567890</code></td>\\n  </tr>\\n</table>\"\n}\n[/block]\n### Names\n[block:html]\n{\n  \"html\": \"<table>\\n<col width=\\\"15%\\\">\\n<col width=\\\"20%\\\">\\n<col width=\\\"15%\\\">\\n<col width=\\\"25%\\\">\\n  <tr>\\n    <th>Entity Name</th>\\n    <th>Description</th>\\n    <th>Examples</th>\\n    <th>Returned Object Structure</th>\\n  </tr>\\n  <tr>\\n    <td>@sys.given-name</td>\\n    <td>Common given names</td>\\n    <td>John<br>Mary</td>\\n    <td>String with the corresponding given name.<br><b>Note:</b> The list contains over 2500 names according to the <a href=\\\"http://www.ssa.gov/OACT/babynames/\\\" target=\\\"_blank\\\">SSA</a>  popular names list.</td>\\n  </tr>\\n  <tr>\\n    <td>@sys.last-name</td>\\n    <td>Common last names</td>\\n    <td>Smith<br>Adams</td>\\n    <td>String with the corresponding last name.</td>\\n  </tr>\\n</table>\"\n}\n[/block]\n### Color\n[block:html]\n{\n  \"html\": \"<table>\\n<col width=\\\"15%\\\">\\n<col width=\\\"20%\\\">\\n<col width=\\\"15%\\\">\\n<col width=\\\"25%\\\">\\n  <tr>\\n    <th>Entity Name</th>\\n    <th>Description</th>\\n    <th>Examples</th>\\n    <th>Returned Object Structure</th>\\n  </tr>\\n  <tr>\\n    <td>@sys.color</td>\\n    <td>Words describing colors</td>\\n    <td>green<br>magenta</td>\\n    <td>String with corresponding color: <code>\\\"carmine\\\"</code></td>\\n  </tr>\\n</table>\"\n}\n[/block]\n### Language\n[block:html]\n{\n  \"html\": \"<table>\\n<col width=\\\"15%\\\">\\n<col width=\\\"20%\\\">\\n<col width=\\\"15%\\\">\\n<col width=\\\"25%\\\">\\n  <tr>\\n    <th>Entity Name</th>\\n    <th>Description</th>\\n    <th>Examples</th>\\n    <th>Returned Object Structure</th>\\n  </tr>\\n  <tr>\\n    <td>@sys.language</td>\\n    <td>Language names</td>\\n    <td>English<br>Japanese</td>\\n    <td>String with corresponding language: <code>\\\"English\\\"</code></td>\\n  </tr>\\n</table>\"\n}\n[/block]\n### Music\n[block:html]\n{\n  \"html\": \"<table>\\n<col width=\\\"15%\\\">\\n<col width=\\\"20%\\\">\\n<col width=\\\"15%\\\">\\n<col width=\\\"25%\\\">\\n  <tr>\\n    <th>Entity Name</th>\\n    <th>Description</th>\\n    <th>Examples</th>\\n    <th>Returned Object Structure</th>\\n  </tr>\\n  <tr>\\n    <td>@sys.music-artist</td>\\n    <td>Matches an artist / group name</td>\\n    <td>Beatles<br>Rihanna<br>Rolling Stones</td>\\n    <td>Artist name as string, e.g. <code>\\\"The Beatles\\\"</code></td>\\n  </tr>\\n  <tr>\\n    <td>@sys.music-genre</td>\\n    <td>Matches a genre name</td>\\n    <td>Blues</td>\\n    <td>Genre as string, e.g. <code>\\\"blues\\\"</code></td>\\n  </tr>\\n</table>\"\n}\n[/block]\n## Developer Entities\n\nYou can create your own entities for your agents, either through web forms, [uploading them in JSON or CSV formats](#download-and-upload-entities), or <a href=\"https://docs.api.ai/docs/entities\" target=\"_blank\">via API calls</a>. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Developer entity names are unique for each agent. Entity names should start with a letter and can contain the following: A-Z, a-z, 0-9, _ (underscore), - (dash).\"\n}\n[/block]\nDeveloper entities can be designed in several different ways. Because of that, we distinguish between different developer entity subtypes.\n\n### Developer Mapping Entities\n\nThis entity type allows the mapping of a group of synonyms to a reference value.\n\nIn natural language, you can often have many ways to say the same thing. For this reason, each mapping entity has a list of entries, where each entry contains a mapping between a group of synonyms (ways that a particular concept could be expressed in natural language) and a reference value (which is canonical).\n\nFor example, a food type entity could have an entry with a reference value of \"vegetarian\" with synonyms of \"veg\" and \"veggie\".\n\nTo create such an entity, leave the checkbox ‘Define Synonyms’ checked and add a reference value and synonyms.\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/E9P9yo46SjeDjwBKvJaO_mapping_entity.gif\",\n        \"mapping_entity.gif\",\n        \"976\",\n        \"357\",\n        \"#2c9ce3\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"In developer entities, reference value is always a string.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"If you need the reference value to be matched in intents, make sure to define it also as one of the synonyms in the same entry.\"\n}\n[/block]\n### Developer Enum Type Entities \n\nEnum type entities contain a set of entries that do not have mappings to reference values. \n\nTo create an enum type entity, uncheck the checkbox ‘Define Synonyms’ and add entries. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/buWh7lMnTBCW7mL20aYb_contact_entity.gif\",\n        \"contact_entity.gif\",\n        \"945\",\n        \"294\",\n        \"#2c9ce4\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nEntries can contain simple words or phrases, or other entities.\n\nWhen an enum type entity contains other entities and they are used with aliases, we call it a composite entity. \n\n### Developer Composite Entities\n\nComposite entities are [enum type entities](#section-developer-enum-type-entities) whose entries contain other entities used with aliases. They return object type values (if not defined otherwise in the parameter table).\n\nComposite entities are most useful for describing objects or concepts that can have several different attributes. \n\nFor example, simple robot moves can have two characteristics: direction and number of steps. We may want to describe all possible combinations of these two characteristics within one entity.\n\nFirst, we create a mapping entity `@direction` for direction options:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/vf7WhcKqTVSiR9IW2OEi_direction_entity.gif\",\n        \"direction_entity.gif\",\n        \"945\",\n        \"314\",\n        \"#2c9ce3\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n Then we create a composite entity `@move` for moves options. Make sure to uncheck the ‘Define synonyms’ checkbox.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/bbAEXYSVTwi6VAU4ymVk_move_entity.gif\",\n        \"move_entity.gif\",\n        \"964\",\n        \"287\",\n        \"#2c9ce3\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n Finally, we’ll use the `@move` entity for annotation in the “Robot moves” intent. When we type in *\"Move 10 steps forward\"*, the annotation appears automatically.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/d4aaf0e-Entities-robot-moves.gif\",\n        \"Entities-robot-moves.gif\",\n        1054,\n        621,\n        \"#339cdd\"\n      ]\n    }\n  ]\n}\n[/block]\nThe phrase *“Move five steps forward”* will return the following parameter values:\n\n    \"parameters\": {\n    \t\"move\": {\n    \t\t\"direction\": \"forward\",\n    \t\t\"steps\": 5\n    \t}\n    }\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"Do not use **@sys.any** in developer entities.\",\n  \"title\": \"Warning\"\n}\n[/block]\n**Related topics:**\n\n- <a href=\"https://docs.api.ai/docs/concept-actions\" target=\"_blank\">Actions and Parameters</a>\n\n\n## User Entities\n\nThese are entities that are defined for a specific end-user. For example, a `@playlist` entity that has generic playlists (since playlists tend to be user-specific) could be defined in a request or for a given session. See <a href=\"https://docs.api.ai/docs/userentities\" target=\"_blank\">/userEntities</a>  for more detailed information.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Download and Upload Entities\"\n}\n[/block]\n##Download Entities\n\nYou can download entities in either JSON or CSV format. To do so, go to Entities from the left side menu, move the cursor over the entity, click the little cloud sign, and choose the format.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/19eyVFHpQfi15XDT6qoJ_entity-download.png\",\n        \"entity-download.png\",\n        \"2134\",\n        \"728\",\n        \"#3387b5\",\n        \"\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\n##Upload Entities\n\nYou can upload entities as either JSON or CSV files. To do so, go to Entities from the left side menu, click on the menu button next to the “Create Entity” button, and choose “Upload entity”.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ZyuteMSWS7OUdIspQsH4_entity-upload.png\",\n        \"entity-upload.png\",\n        \"2214\",\n        \"536\",\n        \"#2b9bdd\",\n        \"\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\n### JSON Format\n\nJSON file should correspond to the <a href=\"https://docs.api.ai/docs/entities#entity-object\" target=\"_blank\">entity object</a> format.\n\n### CSV Format\nCSV file should have the following format:\n\n- Each entry corresponds to a new line.\n- The reference value and synonyms should be separated by commas.\n- Each reference value and synonym should be enclosed in double-quotes.\n- The reference value should be at the beginning of the line.\n- Include the reference value twice if you want it to be matched by the entity.\n\nFor example, a CSV file containing the following line:\n```\"New York City\", \"New York City\", \"NYC\", \"New York City, USA\"```\nwill result in the following entity when uploaded via Api.ai developer console:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/cRqrdVznTb2USKBHgDsb_city-via-csv.png\",\n        \"city-via-csv.png\",\n        \"1538\",\n        \"492\",\n        \"#269ce5\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Allow Automated Expansion\"\n}\n[/block]\n'Allow automated expansion' is a feature of the [developer mapping entities](#section-developer-mapping-entities) that allows an agent to recognize values that have not been explicitly listed in the entity.\n\nFor example, let’s consider an entity with a list of items to buy:\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/150b39f-Allow-automated-expansion-check.png\",\n        \"Allow-automated-expansion-check.png\",\n        1999,\n        763,\n        \"#2e91ca\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\nand an intent containing examples of how users may ask to buy these items:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/e25e53d-Allow-automated-expansion-intent-example.png\",\n        \"Allow-automated-expansion-intent-example.png\",\n        1999,\n        1365,\n        \"#f7f8f7\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\nLet’s imagine that a user asks to buy something that is not listed in the `@item` entity. For example, *“I need to buy some vegetables.”*\n\nWe don’t have ‘vegetables’ in the `@item` entity. However, since the 'Allow automated expansion' is enabled within the `@item` entity, and the user query is similar to the examples provided in the “buy-items” intent, the agent assigns “vegetables” to the parameter “item”.\n\nHere’s what we get the JSON response for this query:\n\n```\n \"result\": {\n    \"source\": \"agent\",\n    \"resolvedQuery\": \"I need to buy some vegetables\",\n    \"action\": \"\",\n    \"actionIncomplete\": false,\n    \"parameters\": {\n      \"item\": \"vegetables\"\n    },\n    \"contexts\": [],\n    \"metadata\": {\n      \"intentId\": \"2c5470c1-2749-45e8-992f-b5dff7645456\",\n      \"webhookUsed\": \"false\",\n      \"intentName\": \"buy-items\"\n    },\n    \"fulfillment\": {\n      \"speech\": \"Ok, adding vegetables.\"\n    }\n ```\n\nIf a user’s input cannot be matched to a specific entity, but is similar to examples listed in the 'User Says' section of an intent, then (using ‘Allow automated expansion), the agent can recognize the pattern and respond appropriately.\n\nThe closer the user input is to the examples from the intent, the better results the 'Allow automated expansion' feature will provide. That’s why it’s important to add as many diverse examples as possible in the ‘User says’ section. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Use this feature with caution:\\n\\n- For finite lists, stick to creating entities containing complete lists instead of providing a partial list and checking 'Allow automated expansion'. \\n- If  'Allow automated expansion' is checked in more than one entity in the same agent, it may cause conflicts and unexpected classification results.\"\n}\n[/block]","excerpt":"","slug":"concept-entities","type":"basic","title":"Entities"}
* [Overview](#overview) * [Using Entities](#using-entities) * [Entity Types](#entity-types) * [System Entities](#section-system-entities) + [Generic](#section-generic) + [Date and Time](#section-date-and-time) + [Numbers](#section-numbers) + [Amounts with Units](#section-amounts-with-units) + [Unit Names](#section-unit-names) + [Geography](#section-geography) + [Contacts](#section-contacts) + [Names](#section-names) + [Color](#section-color) + [Language](#section-language) + [Music](#section-music) * [Developer Entities](#section-developer-entities) + [Developer Mapping Entities](#section-developer-mapping-entities) + [Developer Enum Type Entities](#section-developer-enum-type-entities) + [Developer Composite Entities](#section-developer-composite-entities) * [User Entities](#section-user-entities) * [Download and Upload Entities](#download-and-upload-entities) * [Download Entities](#section-download-entities) * [Upload Entities](#section-upload-entities) + [JSON Format](#section-json-format) + [CSV Format](#section-csv-format) * [Allow Automated Expansion](#allow-automated-expansion) [block:api-header] { "type": "basic", "title": "Overview" } [/block] Entities represent concepts and serve as a powerful tool for extracting parameter values from natural language inputs. The entities that are used in a particular agent will depend on the parameter values that are expected to be returned as a result of agent functioning. In other words, a developer need not create entities for every concept mentioned in the agent – only for those required for actionable data. There are 3 types of entities: **system** (defined by API.AI), **developer** (defined by a developer), and **user** (built for each individual end-user in every request) entities. Furthermore, each of these can be **mapping** (having reference values), **enum type** (having no reference values), or **composite** (containing other entities with aliases and returning object type values). Read a detailed description of each entity type [below](#entity-types). [block:api-header] { "type": "basic", "title": "Using Entities" } [/block] **In <a href="https://docs.api.ai/docs/concept-intents" target="_blank">intents</a>**, you can reference an entity in two ways: - As you write <a href="https://docs.api.ai/docs/concept-intents#section-example-and-template-modes" target="_blank">examples</a> in the ‘User Says’ section, the words and phrases that match entities will be highlighted and <a href="https://docs.api.ai/docs/concept-intents#section-example-annotation" target="_blank">annotated</a> automatically. In this case, parameter names will be the same as the corresponding entity names. - To reference an entity in a <a href="https://docs.api.ai/docs/concept-intents#section-example-and-template-modes" target="_blank">template</a> in the ‘User says’ section, prefix it with an `@`, such as `@entity`. It can also have an alias, which corresponds to the parameter name: `@entity:alias`. **In entities**, reference other entities as `@entity` or `@entity:alias`. Aliases are required if you want to <a href="https://docs.api.ai/docs/concept-actions#section-extracting-values-from-composite-entities" target="_blank">extract reference values from composite entities</a>. [block:api-header] { "type": "basic", "title": "Entity Types" } [/block] ##System Entities These are pre-built entities provided by API.AI in order to facilitate handling the most popular common concepts. Here are some examples of system entities, distinguished by their structure: * System Mapping Entity `@sys.date` matches common date references such as *"January 1, 2015"* or *“The first of January of 2015”* and returns a reference value in ISO-8601 format: `"2015-01-01T12:00:00-03:00"` * System Enum Type Entity `@sys.color` matches most popular colors and returns the matched color as it is without mapping it to any reference value. For example, shades of red, such as *“scarlet”* or *“crimson”*, won’t be mapped to “red” and will return their original values “scarlet” and “crimson”. * System Composite Entity `@sys.unit-currency` is meant for matching amounts of money with indication of currency name, e.g., *“50 euros”* or *“twenty dollars and five cents”*. It returns an object type value consisting of two attribute-value pairs: `{"amount":50,"currency":"EUR"}` See the complete list below. ### Generic [block:html] { "html": "<table>\n<col width=\"15%\">\n<col width=\"20%\">\n<col width=\"15%\">\n<col width=\"25%\">\n <tr>\n <th>Entity Name</th>\n <th>Description</th>\n <th>Examples</th>\n <th>Returned Object Structure</th>\n </tr>\n <tr>\n <td>@sys.any</td>\n <td>Matches any non-empty input (1 or more words)<br><br>See the <i class=\"fa fa-exclamation-triangle\"></i> <strong>Warning</strong> below.</td>\n <td>Find a hotel in @sys.any:location</td>\n <td>String of the user input: <code>\"New York City\"</code></td>\n </tr>\n <tr>\n <td>@sys.url</td>\n <td>Matches a url</td>\n <td>www.api.ai<br>https://api.ai/</td>\n <td>Returns a valid url</td>\n </tr>\n</table>" } [/block] [block:callout] { "type": "danger", "body": "Do not use **@sys.any** in developer entities.", "title": "Warning" } [/block] [block:callout] { "type": "info", "title": "Special system syntax (can be used in the template mode)", "body": "`**` – matches any non-empty string (one or more words). Does not return a value.\n\n`*` – matches any string or nothing. Does not return a value." } [/block] ### Date and Time [block:html] { "html": "<table>\n<col width=\"15%\">\n<col width=\"20%\">\n<col width=\"15%\">\n<col width=\"25%\">\n <tr>\n <th>Entity Name</th>\n <th>Description</th>\n <th>Examples</th>\n <th>Returned Object Structure</th>\n </tr>\n <tr>\n <td>@sys.date</td>\n <td>Matches a date.<br>Both absolute and relative dates are supported.</td>\n <td>January 1<br>Tomorrow<br>January first</td>\n <td>Date in ISO-8601 format: <code>2014-12-31</code></td>\n </tr>\n <tr>\n <td>@sys.date-time</td>\n <td>Matches a date and time.</td>\n <td>Tomorrow at 4 pm<br>January 1 at 3 pm</td>\n <td>Date/time in ISO-8601 format,<br>including time zone:<br><code>2014-08-09T22:45:29+00:00</code></td>\n </tr>\n <tr>\n <td>@sys.date-period</td>\n <td>Matches a date interval.</td>\n <td>April<br>weekend<br>from 1 till 3 of May<br>in 2 days</td>\n <td>Date period in ISO-8601 format: <code>2014-01-01/2014-12-31</code></td>\n </tr>\n <tr>\n <td>@sys.time</td>\n <td>Matches a time.</td>\n <td>1 pm<br>20:30<br>half past four<br>in 2 minutes</td>\n <td>Time in ISO-8601 format (hh:mm:ss): <code>13:30:00</code><br><b>Note:</b> Does not include time zone data.</td>\n </tr>\n <tr>\n <td>@sys.time-period</td>\n <td>Matches a time interval.</td>\n <td>afternoon<br>tonight<br>from 1 till 3:30 pm</td>\n <td>Time period in ISO-8601 format (hh:mm:ss): <code>13:30:00/14:30:00</code><br><b>Note:</b> Does not include time zone data.</td>\n </tr>\n</table>" } [/block] ### Numbers [block:html] { "html": "<table>\n<col width=\"17%\">\n<col width=\"18%\">\n<col width=\"15%\">\n<col width=\"25%\">\n <tr>\n <th>Entity Name</th>\n <th>Description</th>\n <th>Examples</th>\n <th>Returned Object Structure</th>\n </tr>\n <tr>\n <td>@sys.number</td>\n <td>Matches ordinal and cardinal numbers</td>\n <td>1<br>1st<br>two hundred thirty</td>\n <td>Number, such as <code>10</code></td>\n </tr>\n <tr>\n <td>@sys.cardinal</td>\n <td>Matches cardinal numbers</td>\n <td>ten<br>two<br>2<br>10</td>\n <td>Returns number, such as <code>10</code></td>\n </tr>\n <tr>\n <td>@sys.ordinal</td>\n <td>Matches ordinal numbers</td>\n <td>tenth<br>second<br>2nd<br>10-th<br>10th</td>\n <td>Returns integer, such as <code>10</code></td>\n </tr>\n <tr>\n <td>@sys.number-integer</td>\n <td>Matches integers only</td>\n <td>12</td>\n <td>Returns integer, such as <code>12</code></td>\n </tr>\n <tr>\n <td>@sys.number-sequence</td>\n <td>Matches number sequences</td>\n <td>1 2 3 4 5<br>25 35 45 55</td>\n <td>Returns integer, such as <code>123</code></td>\n </tr>\n</table>" } [/block] ### Amounts with Units [block:html] { "html": "<table>\n<col width=\"15%\">\n<col width=\"20%\">\n<col width=\"15%\">\n<col width=\"25%\">\n <tr>\n <th>Entity Name</th>\n <th>Description</th>\n <th>Examples</th>\n <th>Returned Object Structure</th>\n </tr>\n <tr>\n\t<td>@sys.unit-area</td>\n\t<td>Matches a number plus units of area</td>\n\t<td>ten sq ft<br>5 acres</td>\n\t<td>Amount as integer, unit abbreviation as string: <code>{\"amount\":10,\"unit\":\"sq ft\"}</code></td>\n </tr>\n <tr>\n\t<td>@sys.unit-currency</td>\n\t<td>Matches a number plus currency name</td>\n\t<td>5 dollars<br>25 pounds</td>\n\t<td>Integer for amount, string for currency code as per <a href=\"https://en.wikipedia.org/wiki/ISO_4217\" target=\"_blank\">ISO 4217</a>: <code>{\"amount\":5,\"currency\":\"USD\"}</code></td>\n </tr>\n <tr>\n\t<td>@sys.unit-length</td>\n\t<td>Matches a number plus units of length</td>\n\t<td>ten meters<br>5 miles</td>\n\t<td>Amount as integer, unit abbreviation as string: <code>{\"amount\":10,\"unit\":\"m\"}</code></td>\n </tr>\n <tr>\n <td>@sys.unit-speed</td>\n <td>Matches a number plus units of speed</td>\n <td>5 km/h<br>10 miles per hour</td>\n <td>Amount as integer, unit abbreviation as string: <code>{\"amount\":5,\"unit\":\"km h\"}</code></td>\n </tr>\n <tr>\n <td>@sys.unit-volume</td>\n <td>Matches a number plus units of volume</td>\n <td>2 liters<br>100 cc</td>\n <td>Amount as integer, unit abbreviation as string: <code>{\"amount\":2,\"unit\":\"L\"}</code></td>\n </tr>\n <tr>\n <td>@sys.unit-weight</td>\n <td>Matches a number plus units of weight</td>\n <td>5 kilos<br>15 ounces</td>\n <td>Amount as integer, unit abbreviation as string: <code>{\"amount\":5,\"unit\":\"kg\"}</code></td>\n </tr>\n <tr>\n <td>@sys.percentage</td>\n <td>Number + percents</td>\n <td>1%<br>50%<br>25 percent</td>\n <td>Percentage as string, e.g. <code>\"25%\"</code></td>\n </tr>\n <tr>\n <td>@sys.temperature</td>\n <td>Number + temperature units</td>\n <td>12C<br>10°F<br>15 degrees<br>10 degrees celsius</td>\n <td>Amount as integer, unit abbreviation as string: <code>{\"amount\":25,\"unit\":\"F\"}</code><br><b>Note:</b> if unit is not specified (e.g. \"25 degrees\"), \"unknown\" will be returned:<br><code>{\"amount\":25,\"unit\":\"unknown\"}</code></td>\n </tr>\n <tr>\n <td>@sys.duration</td>\n <td>Number + duration units (seconds, hours, days, months etc.)</td>\n <td>5 sec<br>10 minutes<br>5 days<br>3 years</td>\n <td>Amount as integer, unit as string: <code>{\"amount\":10,\"unit\":\"min\"}</code><br><code>{\"amount\":5,\"unit\":\"day\"}</code></td>\n </tr>\n </tr>\n <tr>\n <td>@sys.age</td>\n <td>Number + age units (years old, months old etc.)</td>\n <td>5 y.o.<br>10 months old<br>2 weeks old<br>1 day old</td>\n <td>Amount as integer, unit as string: <code>{\"amount\":5,\"unit\":\"year\"}</code><br><code>{\"amount\":10,\"unit\":\"month\"}</code></td>\n </tr> \n</table>" } [/block] ### Unit Names [block:html] { "html": "<table>\n<col width=\"15%\">\n<col width=\"20%\">\n<col width=\"15%\">\n<col width=\"25%\">\n <tr>\n <th>Entity Name</th>\n <th>Description</th>\n <th>Examples</th>\n <th>Returned Object Structure</th>\n </tr>\n <tr>\n\t\t<td>@sys.currency-name</td>\n\t\t<td>Currencies</td>\n\t\t<td>USD <br> Dollars <br> Euros</td>\n\t\t<td>String: <code>\"USD\"</code></td>\n </tr>\n <tr>\n\t\t<td>@sys.unit-area-name</td>\n\t\t<td>Units of area</td>\n\t\t<td>square meters <br> acres</td>\n\t\t<td>String: <code>\"sq m\"</code></td>\n </tr>\n <tr>\n\t\t<td>@sys.unit-length-name</td>\n\t\t<td>Units of length</td>\n\t\t<td>meters <br> centimeter</td>\n\t\t<td>String: <code>\"cm\"</code></td>\n </tr>\n <tr>\n\t\t<td>@sys.unit-speed-name</td>\n\t\t<td>Units of speed</td>\n\t\t<td>kilometer per hour <br> miles per second</td>\n\t\t<td>String: <code>\"mph\"</code></td>\n </tr>\n <tr>\n\t\t<td>@sys.unit-volume-name</td>\n\t\t<td>Units of volume</td>\n\t\t<td>cubic meters <br> gallons</td>\n\t\t<td>String: <code>\"m3\"</code></td>\n </tr>\n <tr>\n\t\t<td>@sys.unit-weight-name</td>\n\t\t<td>Units of weight</td>\n\t\t<td>kilograms <br> ounce</td>\n\t\t<td>String: <code>\"kg\"</code></td>\n </tr>\n</table>" } [/block] ### Geography [block:html] { "html": "<table>\n<col width=\"15%\">\n<col width=\"20%\">\n<col width=\"15%\">\n<col width=\"25%\">\n <tr>\n <th>Entity Name</th>\n <th>Description</th>\n <th>Examples</th>\n <th>Returned Object Structure</th>\n </tr>\n <tr>\n <td>@sys.address</td>\n <td>Full US address</td>\n <td>111 W Evelyn Ave, Sunnyvale, CA 94086</td>\n <td>String of the user input: <code>\"111 W Evelyn Ave, Sunnyvale, CA 94086\"</code></td>\n </tr>\n <tr>\n <td>@sys.street-address</td>\n <td>Part of US address containing either street name or street name in combination with building number and/or suite/office number. Doesn't include city, state, country or zip code.</td>\n <td>Evelyn Avenue<br>111 West Evelyn Ave<br>111 W Evelyn Avenue Suite 308</td>\n <td>String of the user input: <code>\"111 W Evelyn Avenue Suite 308\"</code></td>\n </tr>\n <tr>\n <td>@sys.zip-code</td>\n <td>5 digit US postal codes,<br>alphanumeric UK postal codes</td>\n <td>94122<br>SW1P 3PA</td>\n <td>String: <code>\"94122\"</code>, <code>\"SW1P 3PA\"</code></td>\n </tr>\n <tr>\n <td>@sys.geo-capital</td>\n <td>World capitals</td>\n <td>Paris<br>Rome</td>\n <td>Name of the capital as per <a href=\"http://www.unece.org/cefact/locode/service/location.html\">UNLOCODE</a> e.g. <code>\"Paris\"</code></td>\n </tr>\n <tr>\n <td>@sys.geo-country</td>\n <td>Short and full names of country</td>\n <td>Great Britain<br>United States</td>\n <td>Short country name as per <br><a href=\"https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes\">ISO 3166-1</a> e.g. <code>\"United States of America\"</code></td>\n </tr>\n <tr>\n <td>@sys.geo-country-code</td>\n <td>Short and full country names, alpha-2, alpha-3 and numeric codes as per <br><a href=\"https://en.wikipedia.org/wiki/ISO_3166-1\">ISO 3166-1</a></td>\n <td>United Sates<br>US<br>USA<br>840</td>\n <td>Strings for name, alpha-2 and alpha-3 codes, integer for numeric code as per <a href=\"https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes\">ISO 3166-1</a>:<br><code>{\"alpha-2\":\"US\",<br>\"alpha-3\":\"USA\",<br>\"name\":\"United States of America\",<br>\"numeric\":840}</code></td>\n </tr>\n <tr>\n <td>@sys.geo-city</td>\n <td>Major cities</td>\n <td>New York<br>Paris</td>\n <td>Name of the city as per <a href=\"http://www.unece.org/cefact/locode/service/location.html\">UNLOCODE</a>, e.g. <code>\"Paris\"</code></td>\n </tr>\n <tr>\n <td>@sys.geo-city-us</td>\n <td>US cities</td>\n <td>New York<br>San Francisco</td>\n <td>Name of the US city as per <a href=\"http://www.geonames.org/\">geonames</a> excluding unique city names like Friendship</td>\n </tr>\n <tr>\n <td>@sys.geo-state-us</td>\n <td>US States</td>\n <td>California<br>Virginia</td>\n <td>Short name of states according to <a href=\"https://en.wikipedia.org/wiki/ISO_3166-2:US\">ISO-3166-2</a>, e.g. <code>\"California\"</code></td>\n </tr>\n <tr>\n <td>@sys.place-attraction-us</td>\n <td>Top US tourist attractions</td>\n <td>Central Park<br>Golden Gate Bridge</td>\n <td>Name of the attraction as string: <code>\"Central Park\"</code></td>\n </tr>\n <tr>\n <td>@sys.airport</td>\n <td>Airport names, IATA and ICAO codes</td>\n <td>Heathrow Airport<br>SFO<br>KSFO</td>\n <td>Strings for country and city of the airport, it's name and IATA/ICAO codes:<br><code>{\"country\":\"United Kingdom\",<br>\"city\":\"London\",<br>\"name\":\"London Heathrow\",<br>\"IATA\":\"LHR\",<br>\"ICAO\":\"EGLL\"}</code></td>\n </tr>\n</table>" } [/block] ### Contacts [block:html] { "html": "<table>\n<col width=\"15%\">\n<col width=\"20%\">\n<col width=\"10%\">\n<col width=\"30%\">\n <tr>\n <th>Entity Name</th>\n <th>Description</th>\n <th>Examples</th>\n <th>Returned Object Structure</th>\n </tr>\n <tr>\n <td>@sys.email</td>\n <td>email</td>\n <td>user@example.com</td>\n <td>Email address as string</td>\n </tr>\n <tr>\n <td>@sys.phone-number</td>\n <td>Phone number</td>\n <td>(123) 456 7890<br>+1 (123) 456-7890</td>\n <td>Phone number without punctuation and spaces, e.g. <code>11234567890</code></td>\n </tr>\n</table>" } [/block] ### Names [block:html] { "html": "<table>\n<col width=\"15%\">\n<col width=\"20%\">\n<col width=\"15%\">\n<col width=\"25%\">\n <tr>\n <th>Entity Name</th>\n <th>Description</th>\n <th>Examples</th>\n <th>Returned Object Structure</th>\n </tr>\n <tr>\n <td>@sys.given-name</td>\n <td>Common given names</td>\n <td>John<br>Mary</td>\n <td>String with the corresponding given name.<br><b>Note:</b> The list contains over 2500 names according to the <a href=\"http://www.ssa.gov/OACT/babynames/\" target=\"_blank\">SSA</a> popular names list.</td>\n </tr>\n <tr>\n <td>@sys.last-name</td>\n <td>Common last names</td>\n <td>Smith<br>Adams</td>\n <td>String with the corresponding last name.</td>\n </tr>\n</table>" } [/block] ### Color [block:html] { "html": "<table>\n<col width=\"15%\">\n<col width=\"20%\">\n<col width=\"15%\">\n<col width=\"25%\">\n <tr>\n <th>Entity Name</th>\n <th>Description</th>\n <th>Examples</th>\n <th>Returned Object Structure</th>\n </tr>\n <tr>\n <td>@sys.color</td>\n <td>Words describing colors</td>\n <td>green<br>magenta</td>\n <td>String with corresponding color: <code>\"carmine\"</code></td>\n </tr>\n</table>" } [/block] ### Language [block:html] { "html": "<table>\n<col width=\"15%\">\n<col width=\"20%\">\n<col width=\"15%\">\n<col width=\"25%\">\n <tr>\n <th>Entity Name</th>\n <th>Description</th>\n <th>Examples</th>\n <th>Returned Object Structure</th>\n </tr>\n <tr>\n <td>@sys.language</td>\n <td>Language names</td>\n <td>English<br>Japanese</td>\n <td>String with corresponding language: <code>\"English\"</code></td>\n </tr>\n</table>" } [/block] ### Music [block:html] { "html": "<table>\n<col width=\"15%\">\n<col width=\"20%\">\n<col width=\"15%\">\n<col width=\"25%\">\n <tr>\n <th>Entity Name</th>\n <th>Description</th>\n <th>Examples</th>\n <th>Returned Object Structure</th>\n </tr>\n <tr>\n <td>@sys.music-artist</td>\n <td>Matches an artist / group name</td>\n <td>Beatles<br>Rihanna<br>Rolling Stones</td>\n <td>Artist name as string, e.g. <code>\"The Beatles\"</code></td>\n </tr>\n <tr>\n <td>@sys.music-genre</td>\n <td>Matches a genre name</td>\n <td>Blues</td>\n <td>Genre as string, e.g. <code>\"blues\"</code></td>\n </tr>\n</table>" } [/block] ## Developer Entities You can create your own entities for your agents, either through web forms, [uploading them in JSON or CSV formats](#download-and-upload-entities), or <a href="https://docs.api.ai/docs/entities" target="_blank">via API calls</a>. [block:callout] { "type": "info", "body": "Developer entity names are unique for each agent. Entity names should start with a letter and can contain the following: A-Z, a-z, 0-9, _ (underscore), - (dash)." } [/block] Developer entities can be designed in several different ways. Because of that, we distinguish between different developer entity subtypes. ### Developer Mapping Entities This entity type allows the mapping of a group of synonyms to a reference value. In natural language, you can often have many ways to say the same thing. For this reason, each mapping entity has a list of entries, where each entry contains a mapping between a group of synonyms (ways that a particular concept could be expressed in natural language) and a reference value (which is canonical). For example, a food type entity could have an entry with a reference value of "vegetarian" with synonyms of "veg" and "veggie". To create such an entity, leave the checkbox ‘Define Synonyms’ checked and add a reference value and synonyms. [block:image] { "images": [ { "image": [ "https://files.readme.io/E9P9yo46SjeDjwBKvJaO_mapping_entity.gif", "mapping_entity.gif", "976", "357", "#2c9ce3", "" ] } ] } [/block] [block:callout] { "type": "info", "body": "In developer entities, reference value is always a string." } [/block] [block:callout] { "type": "info", "body": "If you need the reference value to be matched in intents, make sure to define it also as one of the synonyms in the same entry." } [/block] ### Developer Enum Type Entities Enum type entities contain a set of entries that do not have mappings to reference values. To create an enum type entity, uncheck the checkbox ‘Define Synonyms’ and add entries. [block:image] { "images": [ { "image": [ "https://files.readme.io/buWh7lMnTBCW7mL20aYb_contact_entity.gif", "contact_entity.gif", "945", "294", "#2c9ce4", "" ] } ] } [/block] Entries can contain simple words or phrases, or other entities. When an enum type entity contains other entities and they are used with aliases, we call it a composite entity. ### Developer Composite Entities Composite entities are [enum type entities](#section-developer-enum-type-entities) whose entries contain other entities used with aliases. They return object type values (if not defined otherwise in the parameter table). Composite entities are most useful for describing objects or concepts that can have several different attributes. For example, simple robot moves can have two characteristics: direction and number of steps. We may want to describe all possible combinations of these two characteristics within one entity. First, we create a mapping entity `@direction` for direction options: [block:image] { "images": [ { "image": [ "https://files.readme.io/vf7WhcKqTVSiR9IW2OEi_direction_entity.gif", "direction_entity.gif", "945", "314", "#2c9ce3", "" ] } ] } [/block] Then we create a composite entity `@move` for moves options. Make sure to uncheck the ‘Define synonyms’ checkbox. [block:image] { "images": [ { "image": [ "https://files.readme.io/bbAEXYSVTwi6VAU4ymVk_move_entity.gif", "move_entity.gif", "964", "287", "#2c9ce3", "" ] } ] } [/block] Finally, we’ll use the `@move` entity for annotation in the “Robot moves” intent. When we type in *"Move 10 steps forward"*, the annotation appears automatically. [block:image] { "images": [ { "image": [ "https://files.readme.io/d4aaf0e-Entities-robot-moves.gif", "Entities-robot-moves.gif", 1054, 621, "#339cdd" ] } ] } [/block] The phrase *“Move five steps forward”* will return the following parameter values: "parameters": { "move": { "direction": "forward", "steps": 5 } } [block:callout] { "type": "danger", "body": "Do not use **@sys.any** in developer entities.", "title": "Warning" } [/block] **Related topics:** - <a href="https://docs.api.ai/docs/concept-actions" target="_blank">Actions and Parameters</a> ## User Entities These are entities that are defined for a specific end-user. For example, a `@playlist` entity that has generic playlists (since playlists tend to be user-specific) could be defined in a request or for a given session. See <a href="https://docs.api.ai/docs/userentities" target="_blank">/userEntities</a> for more detailed information. [block:api-header] { "type": "basic", "title": "Download and Upload Entities" } [/block] ##Download Entities You can download entities in either JSON or CSV format. To do so, go to Entities from the left side menu, move the cursor over the entity, click the little cloud sign, and choose the format. [block:image] { "images": [ { "image": [ "https://files.readme.io/19eyVFHpQfi15XDT6qoJ_entity-download.png", "entity-download.png", "2134", "728", "#3387b5", "" ], "sizing": "full" } ] } [/block] ##Upload Entities You can upload entities as either JSON or CSV files. To do so, go to Entities from the left side menu, click on the menu button next to the “Create Entity” button, and choose “Upload entity”. [block:image] { "images": [ { "image": [ "https://files.readme.io/ZyuteMSWS7OUdIspQsH4_entity-upload.png", "entity-upload.png", "2214", "536", "#2b9bdd", "" ], "sizing": "full" } ] } [/block] ### JSON Format JSON file should correspond to the <a href="https://docs.api.ai/docs/entities#entity-object" target="_blank">entity object</a> format. ### CSV Format CSV file should have the following format: - Each entry corresponds to a new line. - The reference value and synonyms should be separated by commas. - Each reference value and synonym should be enclosed in double-quotes. - The reference value should be at the beginning of the line. - Include the reference value twice if you want it to be matched by the entity. For example, a CSV file containing the following line: ```"New York City", "New York City", "NYC", "New York City, USA"``` will result in the following entity when uploaded via Api.ai developer console: [block:image] { "images": [ { "image": [ "https://files.readme.io/cRqrdVznTb2USKBHgDsb_city-via-csv.png", "city-via-csv.png", "1538", "492", "#269ce5", "" ], "sizing": "80" } ] } [/block] [block:api-header] { "type": "basic", "title": "Allow Automated Expansion" } [/block] 'Allow automated expansion' is a feature of the [developer mapping entities](#section-developer-mapping-entities) that allows an agent to recognize values that have not been explicitly listed in the entity. For example, let’s consider an entity with a list of items to buy: [block:image] { "images": [ { "image": [ "https://files.readme.io/150b39f-Allow-automated-expansion-check.png", "Allow-automated-expansion-check.png", 1999, 763, "#2e91ca" ], "sizing": "full" } ] } [/block] and an intent containing examples of how users may ask to buy these items: [block:image] { "images": [ { "image": [ "https://files.readme.io/e25e53d-Allow-automated-expansion-intent-example.png", "Allow-automated-expansion-intent-example.png", 1999, 1365, "#f7f8f7" ], "sizing": "full" } ] } [/block] Let’s imagine that a user asks to buy something that is not listed in the `@item` entity. For example, *“I need to buy some vegetables.”* We don’t have ‘vegetables’ in the `@item` entity. However, since the 'Allow automated expansion' is enabled within the `@item` entity, and the user query is similar to the examples provided in the “buy-items” intent, the agent assigns “vegetables” to the parameter “item”. Here’s what we get the JSON response for this query: ``` "result": { "source": "agent", "resolvedQuery": "I need to buy some vegetables", "action": "", "actionIncomplete": false, "parameters": { "item": "vegetables" }, "contexts": [], "metadata": { "intentId": "2c5470c1-2749-45e8-992f-b5dff7645456", "webhookUsed": "false", "intentName": "buy-items" }, "fulfillment": { "speech": "Ok, adding vegetables." } ``` If a user’s input cannot be matched to a specific entity, but is similar to examples listed in the 'User Says' section of an intent, then (using ‘Allow automated expansion), the agent can recognize the pattern and respond appropriately. The closer the user input is to the examples from the intent, the better results the 'Allow automated expansion' feature will provide. That’s why it’s important to add as many diverse examples as possible in the ‘User says’ section. [block:callout] { "type": "info", "body": "Use this feature with caution:\n\n- For finite lists, stick to creating entities containing complete lists instead of providing a partial list and checking 'Allow automated expansion'. \n- If 'Allow automated expansion' is checked in more than one entity in the same agent, it may cause conflicts and unexpected classification results." } [/block]